User documentation
We use reStructuredText for Sphinx to generate the documentation locally and online on Read the Docs. To learn more about the syntax, check out this quick reference.
- Requirements
Current working directory: nest-desktop/docs
.
To install Sphinx and the Read the Docs theme via pip
:
python3 -m pip install sphinx sphinx_rtd_theme
Development: Build HTML locally
Build the documentation which your created with Sphinx in the docs
folder offline:
rm -r ./_build; make html
Start the python server to serve the documentation locally, i.e. available only on your personal machine.
python3 -m http.server --directory ./_build/html 8002
Then open the URL http://localhost:8002 with your browser.
Publication: Push to ReadTheDocs
The documentation files for the dev branch are automatically rebuilt (and updated) each time a push is made to the repository. The docs for other versions depend on the GitHub tags. The latest tags refers to the latest release version.
Optional: Use Singularity
Build a singularity image:
singularity build doc-sphinx.sif singularity/doc-sphinx.def
Start the Singularity container:
singularity shell doc-sphinx.sif