Only released in EOL distros:   electric fuerte groovy

See also: Doxygen

Generating Local Documentation

For packages in ros-pkg, wg-ros-pkg, and others, rosdoc may automatically be run on the build server so that it can be published on the Web.

Nevertheless, we recommend regularly running rosdoc on your own computer to verify what your documentation looks like before checking it in.

To locally generate the documentation for a package:

roscd rosdoc
./rosdoc <package-name>

This will generate the documentation in rosdoc/doc. It's easiest if you point your Web browser to open rosdoc/doc/<package-name>/html/index.html. Note that you need doxygen installed on your machine (e.g., sudo apt-get install doxygen). You may also need to install sphinx for certain Python packages.

rosdoc configuration files (Epydoc, Sphinx)

New in ROS 0.9

rosdoc supports a YAML-based configuration file that lets you:

• use Epydoc or Sphinx instead of Doxygen
• configure multiple documentation builds per package
• do advance configuration of documentation builds

Enabling via manifest.xml

In order to enable the rosdoc configuration file, you must place the following tag in the <export>...</export> section of the manifest.xml file:

<export>
  <rosdoc config="rosdoc.yaml" />
</export>

rosdoc.yaml should be the path to the configuration file you wish to use.

Basic Syntax

The YAML configuration file should contain a list of dictionaries, where each dictionary has the following standard keys:

• builder: name of documentation builder (doxygen, epydoc, or sphinx)

• output_dir: (optional) name of sub-directory to write documentation to. If you have multiple builders, you must specify this property to avoid builders writing to the same directory.

• name: (optional) name of documentation set (e.g. "Python API")

Each builder may specify additional configuration keys.

Here is a very simple configuration that tells rosdoc to use Epydoc instead of Doxygen for the package

 - builder: epydoc

Here is an example from the roslib package, which performs both C++ and Python API documentation:

 - builder: epydoc
   output_dir: python
 - builder: doxygen
   name: C++ API
   output_dir: c++
   file_patterns: '*.c *.cpp *.h *.cc *.hh *.dox'

Doxygen Builder

The doxygen builder may specify the following additional keys:

• file_patterns: (optional) override the Doxygen FILE_PATTERNS property

• excludes: (optional) override the Doxygen EXCLUDES property

• homepage: ROS 0.10 (optional) link to project home page

rosdoc on ros.org

rosdoc is used automatically generate documentation on the ros.org web server. Frequent updates are made to:

• http://ros.org/doc/api

It is also used to generate the data for the PackageHeader wiki macro that you see on many of the ros.org wiki pages.