Sphinx is a tool for generating documentation for Python code. rosdoc supports documenting packages with Sphinx.
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-sphinxOther 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')
To be done...