melodic noetic   Show EOL distros: 

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.

• robot_upstart

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']

Ref. stackoverflow.com#17004855