Documentation

We are using Sphinx with the Material for Sphinx html theme.

Its configured to provide a Html version of the documentation but could be easily extended to provide a PDF or EPub version as well.

This extensions are configured to enrich the documentation:

• sphinx.ext.autodoc – Include documentation from docstrings

• sphinx_autodoc_typehints - Include typehints in autodoc documentation

• sphinx.ext.autosectionlabel – Allow reference sections using its title

• sphinx.ext.coverage – Collect doc coverage stats

• sphinx.ext.doctest – Test snippets in the documentation

• sphinx.ext.duration – Measure durations of Sphinx processing

• sphinx.ext.extlinks – Markup to shorten external links

• sphinx.ext.intersphinx – Link to other projects’ documentation

• sphinx.ext.napoleon – Support for NumPy and Google style docstrings

• sphinx.ext.viewcode – Add links to highlighted source code

• enum_tools.autoenum - A Sphinx directive for documenting Enums in Python

Development

Use one of the following options to build the documentation:

• Run the live reload server with Python directly:

poetry run python docs/docs_livereload.py

• Or use Docker:

docker compose up --build docs

Both will run a webserver listing on http://localhost:5500 and will automatically rebuild the documentation (and reloading the website inside your browser) if a file in docs or svn2git directory changes.

Build

To finally build the documentation run the following command inside the docs directory:

make html

Or on Windows:

./make.bat html