Contribute

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 https://www.python.org/ on how to install python for your OS.

Note

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.