Documentation
=============

Never forget to update the project documentation. Most likely, it is based on :doc:`Sphinx <sphinx:index>` and resides in the ``docs/`` directory.

To build the docs locally, have a look at the ``make`` :ref:`documentation-targets`. To build the docs during the CI pipeline, have a look at the `docs GitLab CI file <https://git.confirm.ch/confirm/gitlab-ci/-/tree/master/docs>`_.

.. hint::

    Feel free to have a look at the source code of this documentation by either browsing the `GitLab project <https://git.confirm.ch/confirm/guidelines>`_ or using the ``Edit on GitLab`` links in the header.

Documentation language
----------------------

Please check out :ref:`ci:communication` before you start documenting your project.

Get started with Sphinx
-----------------------

Here are some good resources to get started with Sphinx:

- :doc:`sphinx:usage/index`
- :doc:`sphinx:usage/quickstart`
- :ref:`sphinx:rst-index`
- :ref:`sphinx:code-examples`
- :doc:`sphinx:usage/restructuredtext/domains`

Intersphinx
-----------

One big advantage of Sphinx is an extension called :mod:`Intersphinx <sphinx.ext.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:

    .. code-block:: bash

        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 :ref:`PlantUML` chapter. There's a `Sphinx PlantUML Plugin <https://github.com/sphinx-contrib/plantuml/>`_, which can be installed & configured to leverage the :ref:`tools:plantuml-client`:

.. code-block:: python

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

    plantuml = 'plantuml-client'