Documentation for sphinx-automodapi

The sphinx-automodapi package provides Sphinx directives that help faciliate the automatic generation of API documentation pages for Python package modules. It was originally developped for the Astropy project, but is now developed as a standalone package that can be used for any project.

Installation

This extension requires Sphinx 1.7 or later, and can be installed with:

pip install sphinx-automodapi

The extension is also available through conda package management system. It can be installed with:

conda install -c conda-forge sphinx-automodapi

Quick start

To use this extension, you will need to add the following entry to the extensions list in your Sphinx conf.py file:

extensions = ['sphinx_automodapi.automodapi']
numpydoc_show_class_members = False

You can then add an automodapi block anywhere that you want to generate documentation for a module:

.. automodapi:: mypackage.mymodule

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 numpydoc_show_class_members=False option is needed to avoid having methods and attributes of classes being shown multiple times.

By default, sphinx_automodapi will try and make a diagram showing an inheritance graph of all the classes in the module. This requires graphviz to be installed. To disable the inheritance diagram, you can do:

.. automodapi:: mypackage.mymodule
   :no-inheritance-diagram:

The automodapi directive takes other options that are described in more detail in the User guide below.

If you are documenting a module which imports classes from other files, and you want to include an inheritance diagram for the classes, you may run into Sphinx warnings, because the class may be documented as e.g. astropy.table.Table but the class really lives at astropy.table.core.Table. To fix this you can make use of the 'sphinx_automodapi.smart_resolver' Sphinx extension, which will automatically try and resolve such differences. In this, case, be sure to include:

extensions = ['sphinx_automodapi.automodapi',
              'sphinx_automodapi.smart_resolver']

in your conf.py file.

User guide

Dependency Version Guidelines

As a general guideline, automodapi dependencies (at the time of writing, just Sphinx) aim to maintain compatibility with versions <= 2 years old. Dependencies may be newer, however, if specific features become important to help automodapi work better or be more maintainable.