[Documentation] [TitleIndex] [WordIndex

  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

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

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

Step 3: Install Sphinx on your system

Step 4: Create a Sphinx configuration file

Step 5: Rosify your Sphinx configuration file

Step 6: Rosdoc It

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


2024-10-05 12:53