Automatically generating module documentation with automodapi¶
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
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.
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:
- 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.
- Specify whether or not to show the inheritance diagram for classes. This overrides the default global configuration set in
- 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.
- If present, the docstring for the module/package will not be generated. The function and class tables will still be used, however.
- 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 ‘=’).
- 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
- 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 option
:no-inherited-members:allows the user to overrride the global setting.
This extension also adds four sphinx configuration options:
- Should be a boolean that indicates whether to show inheritance diagrams
by default. This can be overriden on a case by case basis with
:no-inheritance-diagram:. Defaults to
- 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
- 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.
- Should be a bool and if
Truemembers that a class inherits from a base class are included in the generated documentation. Defaults to