Sphinx AutoAPI

3.8.0 · active · verified Thu Apr 09

Sphinx AutoAPI is an extension for Sphinx that automatically generates API documentation from your Python code, similar to `sphinx.ext.autodoc` but without needing to explicitly list every module, class, or function. It parses your source code and creates reStructuredText files. The current version is 3.8.0, and it typically releases new minor versions every few months.

Warnings

breaking AutoAPI frequently drops support for older Python versions. Ensure your environment uses Python 3.10 or newer. Version 3.6.0 dropped Python 3.8, and 3.7.0 dropped Python 3.9.
Fix: Upgrade your Python environment to 3.10 or later before upgrading to recent `sphinx-autoapi` versions.
gotcha The `autoapi_dirs` configuration in `conf.py` must correctly point to your Python source code. Relative paths should be correctly resolved, often using `os.path.abspath` and `os.path.join`.
Fix: Verify that `autoapi_dirs` contains correct, absolute paths to your package roots. Misconfigured paths will result in empty or incomplete API documentation.
gotcha Prior to v3.7.0, AutoAPI would silently fail to document objects specified in directives (e.g., `.. py:module::`) that did not exist in the source code. From v3.7.0, an `autoapi.import` warning is issued.
Fix: Update to v3.7.0 or newer to receive warnings for non-existent objects. Always double-check that modules/classes/functions referenced in directives actually exist in your configured `autoapi_dirs`.
breaking Compatibility with the `astroid` library, used for parsing, can be sensitive. `v3.6.1` fixed a breaking change in `astroid`'s `Import` mechanism, indicating that direct `astroid` upgrades might cause issues with older `sphinx-autoapi` versions.
Fix: Always ensure your `astroid` version is compatible with your `sphinx-autoapi` version. It's often best to let `pip` manage `astroid` as a dependency of `sphinx-autoapi` during installation/upgrade.

Install

pip install sphinx-autoapi Install stable version

Imports

autoapi.extension
```
extensions = ['autoapi.extension']
```
AutoAPI is a Sphinx extension, configured by adding 'autoapi.extension' to the 'extensions' list in conf.py, not by direct import in Python code.

Quickstart

To quickly set up Sphinx AutoAPI, first install it and Sphinx. Then, modify your `conf.py` to add `autoapi.extension` to the `extensions` list and configure `autoapi_dirs` to point to the root directory of your Python source code. Finally, reference the generated API documentation from your main `.rst` or `.md` file, typically using a `toctree` that includes `_autoapi/index`.

import os

# In conf.py
project = 'My Project'
copyright = '2024, Author'

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

html_theme = 'sphinx_rtd_theme'

# Point AutoAPI to your source code directory(ies)
# Adjust '../src' to your actual project source path relative to conf.py
autoapi_dirs = [os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src'))]

# Optional: Generate a main index file for AutoAPI
# Then, link to it in your main index.rst via: 
# .. toctree::
#    :maxdepth: 2
#    :caption: API
#    _autoapi/index

view raw JSON →