Automatically generating module documentation with automodapi

Overview

The main Sphinx directive provided by the sphinx-automodapi package is the automodapi directive. As described in the Quick start guide, before you use the directive, you will need to make sure the following extension is included in the extensions entry of your documentation’s conf.py file:

extensions = ['sphinx_automodapi.automodapi']

You can then add an automodapi block anywhere that you want to generate documentation for a module:

.. automodapi:: mypackage.mymodule
   <options go here>

This will add a section with the docstring of the module, followed by a list of functions, and by a list of classes. For each function and class, a full API page will be generated.

The automodapi directive and allowed options are described in more detail below.

In detail

This directive takes a single argument that must be a module or package. It will produce a block of documentation that includes the docstring for the package, an Overview directive, and an automod-diagram directive if there are any classes in the module. If only the main docstring of the module/package is desired in the documentation, use automodule instead of automodapi.

It accepts the following options:

• :include-all-objects:

  If present, include not just functions and classes, but all objects. This includes variables, for which a possible docstring after the variable definition will be shown.

• :inheritance-diagram: / :no-inheritance-diagram:

  Specify whether or not to show the inheritance diagram for classes. This overrides the default global configuration set in automodapi_inheritance_diagram.

• :skip: str

  This option results in the specified object being skipped, that is the object will not be included in the generated documentation. This option may appear any number of times to skip multiple objects.

• :include: str

  This option is the opposite of :skip: – if specified, only the object names that match any of the names passed to :include: will be included in the generated documentation. This option may appear multiple times to include multiple objects.

• :no-main-docstr:

  If present, the docstring for the module/package will not be generated. The function and class tables will still be used, however.

• :headings: str

  Specifies the characters (in one string) used as the heading levels used for the generated section. This must have at least 2 characters (any after 2 will be ignored). This also must match the rest of the documentation on this page for sphinx to be happy. Defaults to “-^”, which matches the convention used for Python’s documentation, assuming the automodapi call is inside a top-level section (which usually uses ‘=’).

• :no-heading:

  If specified do not create a top level heading for the section. That is, do not create a title heading with text like “packagename Package”. The actual docstring for the package/module will still be shown, though, unless :no-main-docstr: is given.

• :allowed-package-names: str

  Specifies the packages that functions/classes documented here are allowed to be from, as comma-separated list of package names. If not given, only objects that are actually in a subpackage of the package currently being documented are included.

• :inherited-members: / :no-inherited-members:

  The global sphinx configuration option automodsumm_inherited_members decides if members that a class inherits from a base class are included in the generated documentation. The option :inherited-members: or :no-inherited-members: allows the user to overrride the global setting.

• :noindex:

  Propagates the noindex flag to autodoc. Use it to avoid duplicate objects warnings.

• :sort:

  If the module contains __all__, sort the module’s objects alphabetically (if __all__ is not present, the objects are found using dir, which always gives a sorted list).

This extension also adds five sphinx configuration options:

• automodapi_inheritance_diagram

  Should be a boolean that indicates whether to show inheritance diagrams by default. This can be overriden on a case by case basis with :inheritance-diagram: and :no-inheritance-diagram:. Defaults to True.

• automodapi_toctreedirnm

  This must be a string that specifies the name of the directory the automodsumm generated documentation ends up in. This directory path should be relative to the documentation root (e.g., same place as index.rst). Defaults to 'api'.

• automodapi_writereprocessed

  Should be a bool, and if True, will cause automodapi to write files with any automodapi sections replaced with the content Sphinx processes after automodapi has run. The output files are not actually used by sphinx, so this option is only for figuring out the cause of sphinx warnings or other debugging. Defaults to False.

• automodsumm_inherited_members

  Should be a bool and if True members that a class inherits from a base class are included in the generated documentation. Defaults to False.

• automodsumm_included_members

  A list of strings containing the names of hidden class members that should be included in the documentation. This is most commonly used to add special class methods like __getitem__ and __setitem__. Defaults to ['__init__', '__call__'].

• automodsumm_properties_are_attributes

  Should be a bool and if True properties are treated as attributes in the documentation meaning that no property specific documentation is generated. Defaults to True.