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.

This extension also adds four 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.