Only released in EOL distros:   electric fuerte groovy

See also: Doxygen

What is rosdoc?

rosdoc is simply a tool that runs an external documentation tool, like Doxygen, Epydoc, or Sphinx, on one or more ROS Packages. rosdoc makes a best effort at providing good default settings to these tools, and in some cases allows these settings to be customized further. The documentation is generated on a package-by-package basis -- rosdoc does not run on ROS Stacks.

In general, tools like Doxygen search all of the source code in a code tree for structured comments, and then use these comments as well as the API of the code to generate HTML files documenting the package. Doxygen and Sphinx also provide additional tools for authoring documentation that is not tied to code API.

rosdoc is used as part of an automated process for updating documentation on ros.org. It is frequently run on packages in ros-pkg and wg-ros-pkg, with the resulting documentation linked to in the "Code API" link of many packages.

rosdoc contains some additional functionality for generating machine-readable documentation files, as well as msg/srv documentation, that are used by the ros.org wiki system and elsewhere. This functionality is mainly only of use those maintaining documentation Web sites.

Generating Local Documentation

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.

NOTE: 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.

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.