Building Documentation

Automatic Build (Default)

By default, the documentation is automatically built and deployed to GitHub Pages on every push to main via the docs GitHub Action. On pull requests, the documentation is built (but not deployed) to catch errors early.

No manual steps are required — merging to main triggers a fresh build of both the Sphinx and Doxygen documentation.

Manual Build (Local)

You can also build the documentation locally, e.g. for previewing changes before pushing.

Read The Docs

This documentation uses ReadTheDocs and Sphinx.

Building

The documentation dependencies are managed via uv. To build:

cd docs/docs_src/read_the_docs
uv run make html

This automatically creates a local .venv, installs the required packages (sphinx, myst-parser, sphinx-rtd-theme), and runs the Sphinx build.

To update the served documentation locally, copy the build output:

cd <repo_root>
cp -r docs/docs_src/read_the_docs/_build/html/* docs/docs/

Doxygen

We also use Doxygen to generate documentation for the C++ code. You can install it via:

sudo apt install doxygen graphviz

Then, you can generate the documentation by running:

doxygen docs/docs_src/doxy/Doxyfile