ROS Package Documentation

We maintain two forms of online documentation for ROS packages:

• wiki pages: home for tutorials and other sorts of information. This is mainly for people running your code.

• auto-generated code documentation: This is mainly for people integrating with or editing your code.

This page describes how to a quick 1-2-3 process to setup your ROS package for both.

Doxygenate your code

It will probably take some time to get all your code properly documented, but we've put together a doxygen guide to get you quickly started.

Create a wiki page for your package

We want every ROS package to have a wiki page so that there is a known location people can check for tutorials and other information, as well as a common Web-writable space for people to contribute notes about that package.

Create it from the PackageTemplate, or enter the package name (case-sensitive) and use this handy button :

For packages that exist in the repository, the package template will automatically link to code API, dependencies, etc.

Follow the style guide when writing the wiki documentation for your package. Look here for macros: WikiMacros

Put the wiki page link in your package.xml or manifest.xml file

Refer to the documentation on the package.xml file. Note that the package.xml file replaced the manifest.xml file that was used in the legacy rosbuild system.

  <url>http://wiki/your_package</url>

Our tools will pull this link out of the package.xml file for various different uses.

Versioning

As time goes on, your package will gain and lose features, and probably change behavior. While we preserve versioned snapshots of documentation associated with releases, the current Wiki + Doxygen documentation should remain valid along the way.

So:

• When you add a feature, such as a method call, annotate it in the documentation to say which version it first appears in, e.g.: "Since 1.2".
• When you want to remove a feature, first deprecate it, mark it as deprecated in the documentation, and do a release. In a subsequent release, after you remove the feature, you can remove it from the documentation.
• When you change behavior, say the look of a graphical interface, and you don't want to mix old and new documentation on the same page, you can move old documentation to a sub-page, and link to it (e.g., "Older documentation").