Epydoc

Epydoc is a tool for generating documentation for Python code. rosdoc_lite supports documenting packages with Epydoc. If you wish to learn more about Epydoc, please consult the official Epydoc documentation.

You don't need to configure and run Epydoc manually in order to generate documentation for your ROS package. Instead, we recommend that you use the rosdoc_lite tool, which can setup your Python path automatically and streamline other setup.

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.

See also: rosdoc_lite, Sphinx, Doxygen

Enabling Epydoc for a Package

There are a couple of steps you need to take in order to enable Epydoc to run on your ROS package with the rosdoc_lite tool.

Step 1: Create a rosdoc config file

• You will need to create a configuration file for rosdoc. By convention, we generally call this file rosdoc.yaml. As the name implies, this configuration file is in YAML format. Here is the simplest possible configuration file that will enable Epydoc for your package:

•  - builder: epydoc

  This configuration will run Epydoc in the default configuration that rosdoc has specified. See the optional step 3 if you wish to override this configuration.

  For more on this configuration file syntax, please see rosdoc_lite.

Step 2: Add a <rosdoc> export to your Manifest

• You will need to add a <rosdoc> export to your manifest.xml so that rosdoc can find your configuration.

•   <export>
      ... other exports ...
      <rosdoc config="rosdoc.yaml"/>    
    </export>

Step 3 (optional): Create an epydoc configuration file

• The default configuration for epydoc works for most simple Python packages, but you may wish to have more control. In order to specify your own epydoc configuration, you first need to modify your rosdoc.yaml:

   - builder: epydoc
     config: epydoc.config

  This tells rosdoc to pass in epydoc.config as the configuration file to Epydoc. If you wish to learn more about these configuration files, please see the official Epydoc documentation.

  Here is an example epydoc.config file from rostopic:

  [epydoc]
  name: rostopic
  modules: rostopic
  inheritance: included
  url: http://ros.org/wiki/rostopic
  frames: no
  private: no