Show EOL distros:
Contents
Sphinx is a tool for generating documentation for Python code. rosdoc_lite supports documenting packages with Sphinx.
See also: rosdoc_lite, Epydoc, Doxygen, Sphinx Domains - Python, ReST-Sphinx Cheat Sheet, Example Project.
Examples
capabilities : from William's capabilities package.
rocon_interactions : from Rocon's interactions package.
jackal_tutorials : presenting prose instruction via 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_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 Sphinx for your package:
- builder: sphinx sphinx_root_dir: doc
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 package.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
A recommended set of answers to the questions sphinx-quickstart asks:$ Root path for the documentation : doc $ Separate source and build directories : n $ Name prefix for templates and static dir : . $ Project name : <PACKAGE NAME> $ Author : <PACKAGE AUTHOR> or <MAINTAINER> $ Project Version : same as package version # see below for automating version from package.xml $ Project release : same as project version $ Source file suffix : .rst # default is .rst $ Master document : index # This is the root document for example, viewing in a browser $ epub builder : n $ autodoc : y $ doctest : y $ intersphinx : y # link between Sphinx documents of different projects $ todo : y $ coverage : y # Document coverage test $ viewcode : y $ Create Makefile : y # Yes!, when you want to build docs locally. If you only intend to build doc on ROS buildfarm, Makefile isn't neccesarry.
Other questions can be left with the default response.
Step 5: Rosify your Sphinx configuration file
You will probably want Sphinx to automatically set version numbers and read documentation strings from your ROS python scripts. If so, modify your conf.py just like any other ros python file. For example, to add automatic version setting from your package.xml, add this to the top of conf.py:
import os import catkin_pkg.package catkin_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) catkin_package = catkin_pkg.package.parse_package(os.path.join(catkin_dir, catkin_pkg.package.PACKAGE_MANIFEST_FILENAME))
and further down in the same file:version = catkin_package.version release = catkin_package.version
If you do this, don't forget to add catkin_pkg to the package.xml:
<build_depend>python-catkin-pkg</build_depend>
Step 6: Rosdoc It
$ sudo apt-get install ros-$ROS_DISTRO-rosdoc-lite $ roscd foo_pkg $ rosdoc_lite .
Configuration options
Generating Python Module Api
By default, sphinx doesn't auto-generate any api docs for your methods and classes. If you want to auto-generate all docs for everything, run the following after creating your package for the first time:
$ roscd foo_pkg $ sphinx-apidoc -o doc src
That will create the appropriate modules.rst and associated package name.rst files.
Customing the Api that gets Documented
An example module api file for sphinx looks like this (this is for rocon_uri):
rocon_uri Package ================= :mod:`rocon_uri` Package ------------------------ .. automodule:: rocon_uri :members: :undoc-members: :show-inheritance: :mod:`exceptions` Module ------------------------ .. automodule:: rocon_uri.exceptions :members: :undoc-members: :show-inheritance: :mod:`rules` Module ------------------- .. automodule:: rocon_uri.rules :members: :undoc-members: :show-inheritance: :mod:`uri` Module ----------------- .. automodule:: rocon_uri.uri :members: :show-inheritance:
Use undoc-members to show all functions and classes, even if they are undocumented. Leave that out (just as for uri module here) to only show documented functions and classes.
Changing Theme
Set the html_theme key in conf.py. A good alternative but still a default theme is agogo:
html_theme = 'agogo'
You can find other default themes in @/usr/share/sphinx/themes@. Using a non-default theme (e.g. the sphinx read the docs theme available via pypi) won't be usable if you wish to release your package on the osrf build farm.
Changelog
You can incorporate your changelog simply by linking it:
> cd doc > ln -s ../CHANGELOG.rst .
and adding it to the toctree
.. toctree:: :maxdepth: 2 rapp_manager_api rapp_api CHANGELOG
or by creating a changelog.rst file in your doc folder that includes your changelog:
.. include:: ../CHANGELOG.rst
and similarly adding it to the toctree
.. toctree:: :maxdepth: 2 rapp_manager_api rapp_api changelog
Troubleshoot
sphinx autodoc not referencing
Make sure conf.py in your document folder contains 'sphinx.ext.autodoc' in the extensions list. E.g.
extensions = ['sphinx.ext.autodoc']