How to build the docs

catkin provides (and uses) some plugins to Sphinx to build documentation. These plugins can be used to provide a common look and feel to the generated documentation.

The first time you want to build catkin-controlled documentation (including catkin’s own documentation), you’ll need to setup your environment.


  1. Install python-catkin-sphinx via apt-get:

    sudo apt-get install python-catkin-sphinx
  2. Alternatively the package is also available via PyPi for non-Debian platforms.

Now you can build documentation for projects that use the ros-theme. For example, to build catkin’s documentation:

git clone git://
cd catkin/doc
make html


Ros theme

To use the ros-theme in your own project’s documentation, add the following line to your

import catkin_sphinx

# Use ROS theme
html_theme = 'ros-theme'

Shell prompts

If you want to document shell prompts (e.g. install instructions), use:

extensions = extensions + ['catkin_sphinx.ShLexer']

and document your snippets using:

.. code-block:: catkin-sh

  $ sudo pip install mystuff

Cmake macro documentation

If you also want to generate docs for cmake files, add:

extensions = extensions + ['catkin_sphinx.cmake']

this will enable the sphinx “.. cmake:macro::” directive.