Directives

Autodoc-Style Directives

You can opt to write API documentation yourself using autodoc style directives. These directives work similarly to autodoc, but docstrings are retrieved through static analysis instead of through imports.

See also

When transitioning to autodoc-style documentation, you may want to turn the autoapi_generate_api_docs option off so that automatic API documentation is no longer generated.

To use these directives you will need to enable the autodoc extension in your Sphinx project’s conf.py:

extensions = ['sphinx.ext.autodoc', 'autoapi.extension']

For Python, all directives have an autodoc equivalent and accept the same options. The following directives are available:

.. autoapimodule::

.. autoapiclass::

.. autoapiexception::

Equivalent to automodule, autoclass, and autoexception respectively. autodoc_inherit_docstrings does not currently work.

.. autoapifunction::

.. autoapidata::

.. autoapimethod::

.. autoapiattribute::

Equivalent to autofunction, autodata, automethod, and autoattribute respectively.

Summary Tables

.. autoapisummary::

Render an autosummary-style table from objects found by AutoAPI’s static analysis.

Each content line is the fully qualified AutoAPI object ID. The table displays the object’s short name and docstring summary, and functions include their signature when available.

For example:

.. autoapisummary::

   package.module.Example
   package.module.helper

This directive is used by AutoAPI’s default templates and accepts the same options as autosummary.

Inheritance Diagrams

.. autoapi-inheritance-diagram::

This directive uses the sphinx.ext.inheritance_diagram extension to create inheritance diagrams for classes.

For example:

sphinx.ext.inheritance_diagram makes use of the sphinx.ext.graphviz extension, and therefore it requires Graphviz to be installed.

The directive can be configured using the same options as sphinx.ext.inheritance_diagram.