{"id":2293,"library":"sphinx-autoapi","title":"Sphinx AutoAPI","description":"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.","status":"active","version":"3.8.0","language":"en","source_language":"en","source_url":"https://github.com/readthedocs/sphinx-autoapi","tags":["sphinx","documentation","api","autodoc"],"install":[{"cmd":"pip install sphinx-autoapi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Sphinx AutoAPI is an extension for Sphinx and requires it to function.","package":"Sphinx","optional":false},{"reason":"AutoAPI uses astroid for parsing Python source code. Specific astroid versions may be required for compatibility, as seen in past breaking changes.","package":"astroid","optional":false}],"imports":[{"note":"AutoAPI is a Sphinx extension, configured by adding 'autoapi.extension' to the 'extensions' list in conf.py, not by direct import in Python code.","wrong":"import autoapi","symbol":"autoapi.extension","correct":"extensions = ['autoapi.extension']"}],"quickstart":{"code":"import os\n\n# In conf.py\nproject = 'My Project'\ncopyright = '2024, Author'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'autoapi.extension',\n]\n\nhtml_theme = 'sphinx_rtd_theme'\n\n# Point AutoAPI to your source code directory(ies)\n# Adjust '../src' to your actual project source path relative to conf.py\nautoapi_dirs = [os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src'))]\n\n# Optional: Generate a main index file for AutoAPI\n# Then, link to it in your main index.rst via: \n# .. toctree::\n#    :maxdepth: 2\n#    :caption: API\n#    _autoapi/index\n","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later before upgrading to recent `sphinx-autoapi` versions.","message":"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.","severity":"breaking","affected_versions":"<3.10"},{"fix":"Verify that `autoapi_dirs` contains correct, absolute paths to your package roots. Misconfigured paths will result in empty or incomplete API documentation.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<3.7.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<3.6.1"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}