How to document
Installation of 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 install python3-sphinx python3-sphinx-rtd-theme python3-breathe pip3 install exhale --user
How to build the documentation
Go to the package with the general documentation (tutorials etc. including this one). Said package is called
Build the sphinx docs for the given package.
sphinx-build docs docs/_out -b html
Open the docs with firefox.
To build and view documentation for another package go to the ROS package (e.g.
bitbots_vision) and run steps 2. and 3. there.
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
- Initialize the directory structure:
To initialize the documentation directory structure in the given package copy the docs folder from another package (e.g.
bitbots_docs). Remember to remove the files in
docs/manualas well as their references in the
docs/index.rstfile, so you can start with a clean docs setup.
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