Maintaining the Documentation

This documentation is built with Sphinx from the repository documentation-cpm-lab. Update it in the same change as the code: a merge request that changes the behavior, a command or a message also changes the pages that describe it.

Versions

The documentation describes one release of the CPM Lab. Its version is release in conf.py and is shown in the title of every page; the current version is 0.3.0. The downloads in assets/ (e.g. the Lichtblick extensions) belong to this release.

After every CPM Lab release (see Releasing the CPM Lab):

  1. Set release in conf.py to the new version.

  2. Copy the .foxe files of the Lichtblick release into assets/, see Lichtblick Release and File Names.

  3. Replace version numbers in the examples, e.g. git checkout 0.3.0.

  4. Merge into main and tag the commit with the release version, e.g. 0.4.0, so the documentation of every release can be rebuilt.

Images

Put images into images/<page>/ and reference them with .. figure:: and an :alt: text. Where an image is still missing, the page shows images/placeholder_missing.svg and a comment above the figure names the file to add:

.. Missing image: replace the placeholder with images/lab_access/lab_overview.png

Find all of them with grep -rn "Missing image" --include=*.rst .. Add the image under that name, point the figure to it and delete the comment.

Building

The repository has a dev container with Sphinx and VS Code tasks:

  • Make html builds the internal version into _build/html.

  • Start webserver serves it with live reload on port 8000.

  • Build public HTML and Start public webserver (port 8001) build and serve the public version.

Every pipeline builds both versions. GitLab Pages publishes the internal version; deploy_unibw_docs publishes the public version on the UniBw server.

Internal and Public Content

The internal documentation, for the development team, is built from the repository as it is. The public documentation is built from a copy from which scripts/strip_internal.py removed the internal content. Mark internal content with these reStructuredText comments:

Marker

Effect in the public version

*internal* in a file or directory name

The file or directory is removed, e.g. deployment/internal_network.rst or images/internal/.

A block between .. internal-only-begin and .. internal-only-end

The block is removed. In its place, a notice tells members of the development team that this part is in the internal documentation and links to the same page there.

.. internal-only-begin silent

The block is removed without a notice, e.g. for a link inside a sentence.

.. public-only with an indented block

The block is a comment internally and becomes regular content publicly, e.g. a placeholder for removed values.

Example from Network, written as it appears in the source (with a space in the markers so that this page is not changed itself):

. . internal-only-begin

2. Set the **Wi-Fi Password** to: ``<the lab password>``

. . internal-only-end

. . public-only

   2. Set the **Wi-Fi Password** to a password of your lab.

In the public version, the password line is replaced by this notice, with a link to the page in the internal documentation, followed by the placeholder:

Notice in the public documentation: You are part of the development team? Read this part in the internal documentation.

The notice that replaces internal content in the public version

Rules:

  • Mark everything internal that must not be public: passwords, internal hosts and URLs, personal data, unreleased plans. When in doubt, mark it.

  • Markers may be indented, e.g. inside a list; the content keeps the indentation of the marker.

  • Never write the markers literally in a page, not even in a code block: the script acts on them and fails on unbalanced markers.

  • Remove links to removed internal pages as well, or the public build fails.

build_public_docs fails if the public version has Sphinx warnings that the internal one does not have, e.g. a link to a removed page, or if a marker is unbalanced. Run Build public HTML before you push.