Sphinx Documentation

We create our documentation site with Sphinx.

Content is written in Markdown and in the CI this is built as a static html site and deployed to GitHub pages

In Sphinx, the markdown files are parsed with myst-parser. There are minor differences in how myst-parser parses the Markdown files in comparison to other Markdown parsers; for instance, a table of contents should be written as described here and a Mermaid diagram should be written as described here.

When transferring the documentation from pure Markdown to Sphinx with Markdown these were the only 2 (small) differences. If something behaves unexpectedly, please refer to the Sphinx documentation or the myst-parser documentation.

Documentation is built in every MR pipeline and this job verifies if there are any broken links, both internal and external, and if there are any Markdown syntax errors.

To verify this locally, run the following commands from within the documentation directory:

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt
make clean
make linkcheck
sphinx-build -b html -W . _build/html
# Or if you're working on the documentation and want to localhost:8000 it:
sphinx-autobuild -b html -W . _build/html