Sphinx

Sphinx is a tool for generating documentation for Python code. rosdoc supports documenting packages with Sphinx.

See also: rosdoc, Epydoc, Doxygen

Enabling Sphinx for a Package

There are a couple of steps you need to take in order to enable Sphinx to run on your ROS package with the rosdoc 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 Sphinx for your package:

•  - builder: sphinx

This configuration will run Epydoc in the default configuration that rosdoc has specified.

• For more on this configuration file syntax, please see rosdoc.

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: Install Sphinx on your system

• On Ubuntu, that requires:

   $ sudo apt-get install python-sphinx

  Other systems have similar package installation commands.

Step 4: Create a Sphinx configuration file

• Put the Sphinx conf.py file in your package directory. To create it:

   $ roscd your_package
   $ sphinx-quickstart

  You will probably want Sphinx to read documentation strings from your ROS python scripts. If so, add this near the top of your conf.py to set sys.path as needed:

  import roslib
  roslib.load_manifest('your_package')

Example

To be done...