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. Please have a look at the coding conventions, too.

Requirements

• Sphinx

• Material Design Theme for Sphinx

Use the working directory: nest-desktop/docs. To install Sphinx and the Read the Docs theme via pip:

wget https://raw.githubusercontent.com/nest-desktop/nest-desktop-docs/main/requirements.txt
python3 -m pip install -r requirements.txt

Make images¶

Make screenshots in web browser or use Kooha to record screen and stores animated images to gif file.

Development: Build HTML locally¶

Build the documentation which your created with Sphinx locally:

make clean 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 8000

Then open the URL http://localhost:8000 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 refer to the GitHub tags or branches. The latest tag is assigned to the latest release version.

Optional: Use Apptainer¶

Build an Apptainer image file:

wget https://raw.githubusercontent.com/nest-desktop/nest-desktop-apptainer/master/recipes/development/doc-sphinx.def
apptainer build doc-sphinx.sif doc-sphinx.def

Start the Apptainer container:

apptainer shell doc-sphinx.sif

Now you are in an Apptainer virtualization in which you can execute the sphinx command.