Documentation¶

Documentation is a crucial part of every project, thus the following guidelines apply to documentations:

Ensure you’ve documented the project
High-level documentations are often preferred over low-level «techie docs»
Think about your target audience / stakeholder before you start documenting
Check out our other documentations for examples
Leverage Emoji’s (and Emoji Finder) in configuration files and alike

Language¶

As mentioned in Communication, our documentation language is English.

Markdown¶

For most projects, the documentation is written in Markdown files.

For GitLab projects, the entrypoint for the documentation is usually the README.md, stored in the project Git root.

Hint

GitLab enhanced Markdown with their GitLab Flavored Markdown version.

Sphinx¶

Most likely, more complex documentation will be based on Sphinx, and reside 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.

Get started with Sphinx¶

Here are some good resources to get started with Sphinx:

Hint

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

Sphinx theme¶

We’re using our own Sphinx theme, which matches the 🎨 Corporate design.

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'