Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
This section is only useful for developers who need to update the documentation.
We use:
- `Sphinx ` for generating the documentation
- `Doxygen ` to extract information from the source code
- `Breathe `_ to link Sphinx and doxygen
- `sphinx-versioning `_ (custom version) to generate a documentation for every version / branch
Install sphinx via pip: ::
sudo pip install Sphinx
sudo pip install sphinxcontrib-bibtex
sudo pip install breathe
sudo pip install git+https://github.com/resibots/sphinxcontrib-versioning.git@resibots
.. warning::
On Mac OSX, do not use `brew install sphinx` because this is not the right sphinx
.. note::
For Python 3, use `pip3` instead of `pip`
Install the Resibots theme for Sphinx::
git clone https://github.com/resibots/sphinx_resibots_theme
export SPHINX_RESIBOTS_THEME="/home/me/path/to/sphinx_resibots_theme"
Install `doxygen `_ via your package manager (e.g. apt-get / brew)::
apt-get install doxygen
In the main limbo directory::
./waf docs
About sphinx and ReStructuredText:
- `There is a tutorial `_,
- `Primer for ReStructuredText `_, the markup language of Sphinx,
- `markup specific to Sphinx `_,
- `About C++ in Sphinx `_
- `Breathe (bridge between sphinx and doxygen) `_
- `Sphinx-versioning `_