Other docs/autodoc

Table Of Contents

Previous topic

Sphinx Customizations/Primer

Next topic

Doxygen : automated documentation of C++ API

This Page

Daya Bay Links

Content Skeleton

Autodoc : pulling reStructuredText from docstrings

Sphinx has an sphinx.ext.autodoc feature that allows reStructuredText to be extracted out of docstrings in your python code. reStructuredText was designed for usage in docstrings, featuring a very light weight markup that is very readable in its source form.

See pages beneath NuWa Python API and use Show Source or view sources at dybgaudi:Documentation/OfflineUserManual/tex/api to see how the autodoc directives are used

  • automodule
  • autoclass

And examine the docstrings at for example:

How to AutoDocifying a module

Create a .rst named after your module in the hierarchy beneath dybgaudi:Documentation/OfflineUserManual/tex/api. Entire modules can be autodoc-ified with a couple of lines (pay attention to the __all__ setting for the python modules):

.. automodule:: <python-dotted-path>

But the resulting docs are liable to include too much. Creating useful docs requires draconian editing to only include what is instructive, beyond that the source code should be consulted.

Creating Useful AutoDocumentation

Creating useful API docs requires full control of what is included (which classes/functions/methods) and how they are grouped/ordered/presented/headered/indexed. Autodoc .rst files need to be source files rather than generated files in order to provide this control.

tips for docstring preparation

A gotcha when improving the docstrings is to forget to cmt <pkg>_python after changing them, as Sphinx is reading them from sys.path not the sources.

docstring debugging

  1. relative indentation is significant to reST, thus use consistent indentation for your docstrings. An example of docstring cleanup is dybsvn:r10222
  2. error reporting seems to get incorrect line nos in docstrings, use non-existing roles eg :red:`dummy` to instrument the docstrings

general reST debugging

  1. leave a blank line before literal blocks
  2. for the colon pointing to a literal block to be visible abutt the the double colon against the last word of the prior para
  3. inline literals cannot start or end with a space