New documentation site

[tillprochaska]

This adds a new documentation site for FollowTheMoney. The site now consists of three separate sections:

• Documentation articles (https://alephdata.github.io/followthemoney/docs)
• Model explorer (https://alephdata.github.io/followthemoney/explorer)
• API reference (https://alephdata.github.io/followthemoney/reference/python)

Some of the features include:

• We now have auto-generated pages for every FtM schema and property type (example). These pages include schema/type descriptions, property listings, the first version that included the schema, …

• RDF XML specs and Python API documentation are generated automatically in GitHub Actions.

• You can reference schemata, property types and Python classes in Markdown and they will be turned into links automatically:

  `schema:Company`
  `type:identifier`
  `class:followthemoney.proxy.EntityProxy`

• Search using Algolia DocSearch. I have slightly customized the crawler to work well for out content structure. Includes a full index of all schemata, types, and properties.

A few aspects of this migration I’d appreciate feedback on:

• I’ve used pdoc to generate Python API docs. Currently, we use Sphinx. I don’t really have any personal preference, pdoc was just easier to set up (requires no configuration). Anyone strong opinions on this? Alternatively, I could setup Sphinx to generate the API docs (but no static documentation pages)

• We previously used a Sphinx plugin to generated a CLI reference for ftm. Pdoc doesn’t support that, and I’ve taken the easy path and have simply pasted the output of ftm --help here.

• Instead of embedding the Python API reference directly on relevant pages, I’ve simply linked out to them (example.

• I was thinking of adding search via Algolia at a later point. This does however require the site to be already online.

• The site is deployed to GitHub Pages. Only changes on the main branch are deployed, there are no PR previews. This is a downside of GitHub Pages, but it simplifies the setup and allows us to reuse the deployment setup we use for other projects at OCCRP.

To do:

• Generate and deploy API docs (at least for the Python lib)
• Remove pre-release @alephdata/followthemoney version once Add property type descriptions to JSON model #913 is merged and released
• Do not use defaultModel exported by the npm package, but import defaultModel.json from the source directly. Otherwise, the docs would always be outdated by one version.
• Add explanations for featured, required props
• Link to YAML schema source
• Add required property indicator to property listings
• Include abstract, generated, edge, temporalExtent on schema pages
• Include matchable, pivot, group on property type pages
• Show hidden in property listings

To do before merging:

• Change branch in options.json to main
• Change deploy condition in Actions workflow (only deploy on push to master)
• Delete existing docs directory and rename site to docs?
• Update Makefile (remove namespace target, XML is now built in CI)
• Figure out if the Read the docs subdomain can be redirected?