Generating tables of module objects with automodsumm

Overview

The automodsumm directive takes all objects in a module and generates a table of these objects and associated API pages. The automodapi directive then calls automodsumm once for functions and once for classes, and adds the module docstring - but effectively, the bulk of the work in creating the API tables and pages is done by automodsumm.

Nevertheless, in most cases, users should not need to call automodsumm directly, except if finer control is desired. The syntax of the directive is:

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

The automodsumm directive is described in more detail below.

In detail

This directive will produce an “autosummary”-style table for public attributes of a specified module. See the sphinx.ext.autosummary extension for details on this process. The main difference from the autosummary directive is that autosummary requires manually inputting all attributes that appear in the table, while this captures the entries automatically.

This directive requires a single argument that must be a module or package.

It also accepts any options supported by the autosummary directive- see sphinx.ext.autosummary for details. It also accepts some additional options:

  • :classes-only:

    If present, the autosummary table will only contain entries for classes. This cannot be used at the same time with :functions-only: or :variables-only:.

  • :functions-only:

    If present, the autosummary table will only contain entries for functions. This cannot be used at the same time with :classes-only: or :variables-only:.

  • :variables-only:

    If present, the autosummary table will only contain entries for variables (everything except functions and classes). This cannot be used at the same time with :classes-only: or :functions-only:.

  • :skip: obj1, [obj2, obj3, ...]

    If present, specifies that the listed objects should be skipped and not have their documentation generated, nor be included in the summary table.

  • :allowed-package-names: pkgormod1, [pkgormod2, pkgormod3, ...]

    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: or :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 flags :inherited-members: or :no-inherited-members: allows overrriding this global setting.

  • :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 three sphinx configuration options:

  • automodsumm_writereprocessed

    Should be a bool, and if True, will cause automodsumm to write files with any automodsumm sections replaced with the content Sphinx processes after automodsumm 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, will cause automodsumm to document class members that are inherited from a base class. This value can be overriden for any particular automodsumm directive by including the :inherited-members: or :no-inherited-members: options. 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.

automod-diagram directive

This directive will produce an inheritance diagram like that of the sphinx.ext.inheritance_diagram extension.

This directive requires a single argument that must be a module or package. It accepts no options.

Note

Like ‘inheritance-diagram’, ‘automod-diagram’ requires graphviz to generate the inheritance diagram.