Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time
.. toctree::




Automatic Python API reference documentation generator for Sphinx, inspired by Doxygen.

AutoAPI is a Sphinx extension that allows to automatically generate API reference documentation for Python packages (:doc:`example <autoapi/documented>`), recursively, without any intervention from the developer. It will discover all the package modules and their public objects and document them.


  1. Install:

    pip install autoapi

    Or if using Virtualenv or Tox (and you should) add it to your requirements.txt (or if you want to separate your package requirements from the development requirements).

  2. Add AutoAPI to your extensions:

    In your Sphinx configuration file add autoapi.sphinx:

    extensions = [

    Make sure to have autodoc and inheritance_diagram too because the default generation template will use them.

  3. Configure AutoAPI with the root modules you want to generate documentation for:

    In your project file define the autoapi_modules dictionary variable with the module names as keys:

    autoapi_modules = {'mymodule': None}

    This dictionary maps the module names with the options for generation for that module:


    bool [False] The package to document is modeled as a tree, and each submodule is a node of that tree. A node is considered relevant if it has a public interface that needs to be documented or it is required to reach a node that has a public interface. If prune is set to True, all branches that aren't relevant will be silently ignored. If False, all branches will be generated, even for those modules that do not possess a public interface.


    bool [True] Regenerate the reference pages even if they exists. AutoAPI by default is automatic, but if you prefer to use it like autosummary_generate and create stub pages for later manual edition set the override flag to False and commit the generated pages to your version control. On the other hand, if fully automatic reference documentation generation is preferred put the output folder of this module in your version control ignore file.


    str ['module'] Template name to use. This option can be changed to use different templates for different modules. See the section :ref:`different_templates`.


    str [module] Output folder to generate the documentation for this module relative to the folder where your is located. By default the output folder is the same as the module key. For example, for mymodule the following could be generated:

    `-- mymodule
        |-- mymodule.rst
        |-- mymodule.submodule.rst
        `-- mymodule.another.rst

    For example, a custom configuration could be:

    autoapi_modules = {
       'mymodule': {
          'override': False,
          'output': 'auto'
  4. Reference your documentation in your Sphinx project:

    Add in one of your reST source files a reference to the documentation.

    .. toctree::

    And, optionally, you can link to it like this:

    See the :doc:`reference documentation <mymodule/mymodule>`.
  5. Prepare your codebase:

    Now in your modules, put all the elements you want to document in the __all__ or the __api__ listings. See the section :ref:`documenting_the_code`.

Documenting the code

The strict minimum:

  • List all public objects in your __all__ (preferred) or __api__.
  • Put at least a docstring with a brief in your module, in all your public classes, methods, functions and variables.

Even better:

  • Use the autodoc syntax in your docstrings (or use other that autodoc supports).

Use the following example as a guide. Check corresponding :doc:`documentation <autoapi/documented>` produced by AutoAPI.

.. literalinclude::


AutoAPI provides several ways to customize the output generated by the tool. AutoAPI uses the Jinja2 template engine for page generation.

Overriding the default template

The default template used by autoapi can be customized to meet your needs. To do so, copy the default template and put it in your templates_path (usually _templates) folder under:


The next run Sphinx will use it for all your modules documentation generation.

Using different templates

Instead of providing a single template for all your modules you can also setup different templates for different modules. For example, for you module mymod you choose to use the template mymodtemplate. In your the following is setup:

# autoapi configuration
autoapi_modules = {
    'mymod': {'template': 'mymodtemplate'}

Now you need to place your template in:


And AutoAPI will use it for documenting mymod only.


This is a list of possible improvements, its doesn't mean they are good idea or that they should be implemented.

  • Automatically hook the auto-generated files to the index document toctree.
  • Extend the __api__ key to support a dictionary so each element that requires documentation can provide attributes individually (like show special members).
  • Generate an optional module index page with a different template (called index.rst at the module generation folder).




Copyright (C) 2015-2020 KuraLabs S.R.L

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.