Documentation

Never forget to update the project documentation. Most likely, it is based on Sphinx and resides in the docs/ directory.

To build the docs locally, have a look at the make Documentation targets. To build the docs during the CI pipeline, have a look at the docs GitLab CI file.

Hint

Feel free to have a look at the source code of this documentation by either browsing the GitLab project or using the Edit on GitLab links in the header.

Documentation language

Please check out 💬 Communication before you start documenting your project.

Get started with Sphinx

Here are some good resources to get started with Sphinx:

• Using Sphinx

• Getting Started

• reStructuredText

• Showing code examples

• MOVED: Domains

Intersphinx

One big advantage of Sphinx is an extension called Intersphinx, which can generate automatic links to the documentation of objects in other projects.

Hint

To see all links of an Intersphinx mapping file, you can use the following command:

python3 -msphinx.ext.intersphinx {URL to .inv file}

PlantUML in Sphinx

When you’re looking to include diagrams in your docs, have a look at the PlantUML chapter. There’s a Sphinx PlantUML Plugin, which can be installed & configured to leverage the plantuml-client:

extensions = [
    # …
    'sphinxcontrib.plantuml',
    # …
]

plantuml = 'plantuml-client'