Documentation

The documentation is generated via Sphinx using the book theme.

Building the documentation

To be able to build the documentation, the documentation dependencies have to be installed:

python -m pip install -e ".[doc]"

To build the documentation, simply execute the Makefile inside the docs folder:

cd docs
make all_versions

This will build the documentation for all versions (see next section). To only build it for your current version, execute make local. The homepage of the documentation can be found in build/html/local/index.html.

Building for all versions

In helpers/generate_versions.py, build/html/versions.json is created, containing a list of all the versions along with their names and links. Then, for each of these versions, the files from the corresponding Git branch or version tag are saved to build/html/src/{version} using git archive. In this folder, the documentation is built with make local. The resulting folder, which contains the HTML files (build/html/src/{version}/docs/build/html/local) is then moved to the collective documentation (build/html/{version}).

Remark on docstrings

The docstrings in this project are written in numpy style. Please read the numpy style documentation to get to know the syntax and the different sections.

If you are using vscode, there is an extension called Python Docstring Generator which automatically generates the docstring from the function’s definition in the numpy format (the numpy style has to be specified in the extension’s settings).