Generating tables of module objects with automodsumm — sphinx-automodapi 0.22.0 documentation

# 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.