How to document

Our documentation is published under doku.bit-bots.de and will automatically be regenerated from the package bitbots_meta/bitbots_tools/bitbots_docs and deployed by our Jenkins CI.

Installation of system dependencies

We are using Sphinx and the following extentions to generate our documentation: breathe, exhale. The correct version of the extentions must be installed.

sudo apt remove python-sphinx
sudo apt install python3-sphinx python3-sphinx-rtd-theme python3-breathe
pip3 install exhale --user

How to build the documentation

To build the general documentation (tutorials etc. including this one), run the following command:
```
catkin build bitbots_docs --no-deps --make-args Documentation
```
To build documentation for another package (with activated documentation), run the following command by replacing <package> by your package name:
```
catkin build <package> --no-deps --make-args Documentation
```
If you happen to build documentation a lot and don’t want to always type the whole command, you can define a catkin alias by creating the following file:
```
# ~/.config/catkin/verb_aliases/01-doc.yaml
---
doc: build --make-args Documentation --
```

How to write documentation for a package

In every package (with activated documentation) you can find a directory, called docs/ including the configuration file (docs/conf.py) and the root-document (docs/index.rst).

Preferably create your .rst documents in the directory docs/manual, then reference them in the docs/index.rst as follows:

.. toctree::
    :maxdepth: 1
    :glob:
    :caption: Manuals:

    manual/*

Activate documentation for a package

To be able to actually succeed in building documentation for a package as described above that package must have documentation enabled. This can be done with the following steps and automatically creates the files docs/conf.py and docs/index.rst

package.xml:
The package.xml describes the package to the build system. You need to add a dependency to bitbots_docs.
<package> <depend>bitbots_docs</depend> </package>
CMakeLists.txt:
This file describes how exactly a package is built. First we need to add the bitbots_docs dependency here as well in order to make additional cmake commands available.
find_package(catkin COMPONENT bitbots_docs)
This registered the command enable_bitbots_docs() which is used to register the Documentation target for this package and thus enables building documentation.
enable_bitbots_docs()
.gitignore:
These additions are not strictly necessary but since we use git for all our packages you should do it anyways. It is only required once per repository and not per package.
# auto-generated documentation **/docs/_build **/docs/_out **/docs/cppapi **/docs/pyapi

Note

See Continuous Integration for information about building the documentation automatically via Jenkins