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