Table Of Contents

Previous topic

Migrating from Fuerte catkin

Next topic

Developers Guide

This Page

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.

Setup

  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://github.com/ros/catkin.git
cd catkin/doc
make html

Usage

Ros theme

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

import catkin_sphinx
html_theme_path.append(os.path.join(os.path.dirname(catkin_sphinx.__file__),
                                    'theme'))

# 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.