How to document¶
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 (
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
package.xmldescribes the package to the build system. You need to add a dependency to
<package> <depend>bitbots_docs</depend> </package>
This file describes how exactly a package is built. First we need to add the
bitbots_docsdependency 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.
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
See Continuous Integration for information about building the documentation automatically via Jenkins