Generating tables of module objects with automodsumm¶
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
Nevertheless, in most cases, users should not need to call
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.
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.
- If present, the autosummary table will only contain entries for classes. This cannot be used at the same time with
- If present, the autosummary table will only contain entries for functions. This cannot be used at the same time with
- 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
: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.
- The global sphinx configuration option
automodsumm_inherited_membersdecides if members that a class inherits from a base class are included in the generated documentation. The flags
:no-inherited-members:allows overrriding this global setting.
This extension also adds two sphinx configuration options:
- Should be a bool, and if
True, will cause automodsumm to write files with any
automodsummsections replaced with the content Sphinx processes after
automodsummhas 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
- 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
:no-inherited-members:options. Defaults to
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.
Like ‘inheritance-diagram’, ‘automod-diagram’ requires graphviz to generate the inheritance diagram.