[Documentation] [TitleIndex] [WordIndex

DEPRECATION NOTICE: rosdoc is now deprecated in favor of rosdoc_lite

Only released in EOL distros:  

documentation: rosdoc

Package Summary

rosdoc wraps documentation tools like doxygen, sphinx, and epydoc with ROS package semantics to auto-generate documentation for ROS packages. rosdoc also supports online documentation, like the ROS wiki.

documentation: rosdoc

Package Summary

rosdoc wraps documentation tools like doxygen, sphinx, and epydoc with ROS package semantics to auto-generate documentation for ROS packages. rosdoc also supports online documentation, like the ROS wiki.

documentation: rosdoc

Package Summary

rosdoc wraps documentation tools like doxygen, sphinx, and epydoc with ROS package semantics to auto-generate documentation for ROS packages. rosdoc also supports online documentation, like the ROS wiki.

documentation: rosdoc

Package Summary

rosdoc wraps documentation tools like doxygen, sphinx, and epydoc with ROS package semantics to auto-generate documentation for ROS packages. rosdoc also supports online documentation, like the ROS wiki.

See also: Doxygen, Sphinx, and Epydoc

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. We recommend trying rosdoc instead of attempting to setup those tools manually, as it provides shortcuts for configuring those tools and can also import additional ROS information.

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.

By default, rosdoc will use Doxygen to generate the documentation for a package. If you wish to use another tool, like Epydoc or Sphinx, you must use a rosdoc configuration file. This is described below. For C/C++, only Doxygen is advised.

The documentation that is generated will depend on which tool is used, as each tool behaves differently. For example, Doxygen will extract API details from all source files found in the package (see Doxygen for more).

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 to those maintaining documentation Web sites.

Usage

You can use rosdoc to generate local copies of documentation. When you run the rosdoc command, it will generate documentation into the 'doc' folder of the local directory.

Usage: rosdoc [options] [packages...]

Options:
  -h, --help            show this help message and exit
  -n NAME, --name=NAME  Name for documentation set
  --paths=PATHS         package paths to document
  -o OUTPUT_DIRECTORY   directory to write documentation to

Generate documentation for specific packages:

or simply

Generate documentation for all packages:

Generate documentation in your home directory:

(Again rosrun combination works here too.)

Automatically Generated Online Documentation

rosdoc is automatically run for packages in ros-pkg, wg-ros-pkg, and others. The resulting documentation is uploaded to ros.org and is linked in the "Code API" links that you see on various package pages, like rospy.

Even if rosdoc is automatically generated for your package, 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)

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

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:

Each builder may specify additional configuration keys.

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'

Builder: Doxygen

The "doxygen" builder will enable running Doxygen on a package. As Doxygen is the default builder for any package, it is only necessary to configure this option if:

The "doxygen" builder may specify the following additional keys:

New in Diamondback

Builder: Epydoc

The "epydoc" builder will enable running Epydoc on a package.

Note: Epydoc's "introspection" capability currently breaks when trying to process some ros python modules, so this feature should not be enabled in a custom epydoc config file.

The "epydoc" builder may specify the following additional keys:

Builder: Sphinx

The "sphinx" builder will enable running Sphinx on a package.

The "sphinx" builder may specify the following additional keys:

Builder: external

New in C Turtle

The "external" builder specifies that you wish to link to externally generated documentation. rosdoc will generate a landing page with the link to the specified URL.

The "external" builder takes in the following additional keys:

Builder: rosmake

Removed in ROS Fuerte: this builder has been removed as it has problematic side-effects.

The "rosmake" builder specifies that rosdoc must run rosmake on the package before generating documentation. This is most frequently used in packages with auto-generated code, such as swig-wrappers.

The "rosmake" builder takes no additional configuration. The "name" and "output_dir" options are ignored.

Linking to External Third Party Documentation

NOTE: starting with C Turtle, you can also use the 'external' builder specified above

For third party packages, rosdoc can automatically create a doxygen main page for the package, that includes a link to the third party documentation. To do so, you must add a line to your manifest.xml

<export>
  <doxymaker external="http://link.to.external/page.html"/>
</export>

rosdoc on ros.org

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

It is also used to generate the data for the PackageHeader, StackHeader and MsgSrvDoc wiki macros that you see on many of the ros.org wiki pages.

Roadmap/Stability

The rosdoc tool itself is stable, though it has many internal features and functionality that are changed to support the documentation needs of ros.org. In the future, the rosdoc tool will hopefully be evolved to better support the configuration requirements of the documentation tools it invokes (i.e. Doxygen), and it will also better support documenting specific stacks.

The code API of rosdoc should not be used as it is an internal library that is frequently changed.


2024-03-23 12:55