If you want to contribute to any of the nuts foundation projects or to this documentation, please fork the correct project from Github and create a pull-request.

Documentation contributions

Documentation is written in Restructured Text. A CheatSheet can be found here.

You can test your documentation by installing the required components.

You first have to install python, check on how to install python for your OS.


MacOS (currently) comes with Python 2 preinstalled which has been deprecated as of January 1st, 2020. It’s recommended to upgrade to Python 3 before proceeding.

Next you have to install pip. Then install the following components using pip:

pip install sphinx --user
pip install recommonmark
pip install sphinx_rtd_theme
pip install sphinxcontrib.httpdomain
pip install sphinx-jsonschema
pip install rst_include

For MacOS make sure the sphinx executables are added to your PATH (e.g. for Python 3.8):

export PATH=$HOME/Library/Python/3.8/bin:$PATH

Then you can generate the documentation locally with:

make html

For small changes you might want to add the clean directive:

make clean html

The documentation will then be available from _build/html/index.html

Documentation initialisation

When starting a new project, the documentation can be initialised using:

sphinx-quickstart docs

This will start the interactive setup of sphinx with a document root at docs. For Nuts projects we use that specific directory for documentation in a code project. You might have noticed that the nuts-documentation repo uses the root directory as documentation root.

Most defaults will do, although we use intersphinx to go back-and-forth between the different sub-projects.