FlowKit's documentation is built using Mkdocs.

• Docker
• Pipenv

To build the docs, first install the necessary dependencies by running pipenv install (in the docs/ subfolder). Once this completes, you can build the docs by running pipenv run build, after sourcing the top level development_environment file by running set -a && . ./development_environment && set +a in the project root.

This will create any necessary Docker containers, run all notebooks, generate markdown for the APIs, and finally build all the resulting markdown to HTML. Built docs will be in the flowkit-docs directory.

For local development, you can also run pipenv run serve, which will build the docs, and then start a live reloading web server. You can view the docs at http://localhost:8000, and any changes you make to markdown files in the build directory will be reflected immediately.

Alternatively, you can build the docs by sourcing development_environment and running

DOCKER_SERVICES="flowdb_synthetic_data flowapi flowmachine flowmachine_query_locker" make up

in the project root to bring up the required containers, and then running pipenv run mkdocs directly.

To edit the docs, you should make changes to the source directory.

While editing, you can use pipenv run serve to get an automatically rebuilding and reloading version of the docs, by default accessible at http://localhost:8000.

The build.sh script:

1. If not on CircleCI, runs docker-compose to bring up a redis container, and the FlowDB synthetic data container.
2. Uses nbconvert on all notebooks found in source and (optionally) executes them.
3. Generates markdown API documentation for FlowMachine at build/components/flowmachine
4. Generates markdown API documentation for FlowClient at build/components/flowclient
5. Builds HTML from the markdown using mkdocs

By default, Pandas output is as HTML tables, which don't get styled nicely in the resulting markdown. To avoid this, a modified nbconvert executor (ExecuteWithPreamble), from the nbconvert-utils package is used to inject the notebook_preamble.py script at the start of each notebook, and hide that cell from the markdown. This filters warnings, makes pandas output appear as markdown tables (which then get rendered nicely by mkdocs), and generates an API access token.

Because sphinx does not have a markdown builder, the API documentation is generated using mktheapidocs, which produces markdown from numpy formatted docstrings and uses numpydoc for parsing.

In addition to markdown files, Jupyter notebooks can be used. Any notebooks present in the docs directory will be executed and converted automatically as part of the build process.

In addition to code blocks, you can also include mermaid diagrams in documentation pages, by enclosing the diagram in a code block:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;