Documentation with Sphinx

We use Sphinx to generate the documentation for the project. For a general introduction into sphinx, please check out the following resources:

• Code Refinery lesson on documentation

• quick start guide

• tutorial

• sphinx syntax

Updating the documentation

All documentation that sphinx needs to parse, should stored in the /docs folder. The documentation itself can be of .rst or .md format. All files to be included in the documentation need to be listed in the file index.rst. This file also generates the table of contents. Simple add a new .rst or .md file in the sphinx folder (or any subfolder) and add a link to it in index.rst.

The API references are generated with sphinx-autosummary. This project follows the Numpy style for writing docstrings.

The API references are build from the file docs/api.rst. This file contains the instructions for sphinx to retrieve all the docstrings from the functions within each of the modules in the project. The resulting documentation is stored in the (temporary) folder docs/_autosummary.

We use the solution in this StackOverflow solution to set up recursive generation of the api documentation.

Sphinx configuration

Sphinx is configuration can be found in the file docs/conf.py. Here, you can add additional features through extensions or change the theme. Note, you might need to install the extensions or themes with pip. If so, please add them as dependencies in setup.cfg under the development dependencies.

Building the documentation locally

If you want to view the documentation locally on your own system, please install the openddm package with its development dependencies with

pip install -e .[dev]

It is also recommended (but not required) to install Make.

You can build the documentation locally using Make with

cd docs/
make html

or without Make with

sphinx-build ./docs _build

You can then view the documentation by opening the file docs/_build/html/index.rst in a webbrowser.

Automatically publish a documentation website

We have set up a GitHub action to build and publish the documentation when we push a new commit to the master branch. The workflow can be found in .github/workflows/CI_pages.yml and the webpage at https://koenderinklab.github.io/ddmPilotCode/.

Publishing documentation as a website is handled by GitHub with GitHub pages. In the settings of the repository, under the tab pages, we have pointed GitHub to the branch gh-pages to find the (sphinx-build) documentation. When the CI_pages action is run, it will build the documentation with sphinx and push the changes to the branch gh-pages. GitHub will then update the webpages accordingly.