Expanding the Docs

Building Locally

If you wish to compile the online docs locally you will need the following dependencies:

sudo apt-get install python-pip doxygen python-pyaudio
pip install sphinx exhale breath sphinx_rtd_theme recommonmark --user

The html documentation can then be compiled by:

cd ~/catkin_ws/src/voxblox/voxblox/docs
make html

this will generate a folder docs/_build with the homepage of the website located at docs/_build/html/index.html.

Adding a Page

Simply add either a .rst or .md file to the docs/pages folder, it will automatically be found and included in the docs. Note that the markdown parser used does not support tables.

The Docs Generation Structure

The docs are generated by Exhale which automates the combined use of Doxygen, Sphnix and Breathe. The docs use the readthedocs theme and are hosted on readthedocs The following files are used in the docs generation:

conf.py
A python script that controls how Sphinx runs, responsible for loading the Breathe and Exhale extensions and setting up the project.
Doxyfile
A file containing all the options used by doxygen.
index.rst
The homepage of the generated website in .rst format. It also contains the specifications for the Sphinx TOC Tree which is displayed on the websites sidebar.
logo.gif
The image shown as the logo of the project.
Makefile
Builds the website using Sphinx.
requirements.txt
Used by readthedocs to install the Exhale extension.
pages
Folder containing the additional wiki pages in either .rst or .md format.

Using the Same Documentation on Another Project

To use the same approach on another project perform the following:

  1. Copy the Docs folder to the root directory of the project.
  2. Change the value of the name variable in conf.py.
  3. Modify the index.rst to fit your new project.
  4. Change the contents of the pages folder to your projects .md and .rst files.
  5. Add docs/_build, docs/doxyoutput and docs/api to your .gitignore file (for building locally).
  6. Push the changes to github.
  7. Create a new project on readthedocs.io and in advanced settings set the Requirements file path to docs/requirements.txt.