Sphinx Autodoc2

0.5.0 · active · verified Thu Apr 16

Sphinx Autodoc2 is a Sphinx extension designed to automatically generate API documentation for Python packages. Unlike the traditional `sphinx.ext.autodoc`, it uses static analysis of the source code, eliminating the need to install or import the package for documentation generation. This approach also correctly handles `TYPE_CHECKING` blocks and avoids import side-effects. It supports both reStructuredText (RST) and MyST (Markdown) docstrings and offers highly configurable analysis and output options. The analysis and rendering are decoupled, allowing it to be used outside of Sphinx via a command-line tool.

Common errors

```
WARNING: autodoc2_packages must not be empty [autodoc2.config_error]
```
cause The `autodoc2_packages` list in `conf.py` is either missing or empty.

fix Add the path(s) to your Python package(s) to the `autodoc2_packages` list in `conf.py`. For example: `autodoc2_packages = ['../your_package_root']`.
```
WARNING: <filename>.rst:<line_number>: WARNING: reference target not found: <SomeType>
```
cause Sphinx's nitpicky mode can't resolve a type hint or reference, often for types from external libraries, or due to a mismatch in `intersphinx` configuration.

fix Ensure `intersphinx` is configured correctly for all external dependencies in `conf.py`. You might also need to map problematic type names using `autodoc2_replace_annotations` or `autodoc2_replace_bases`.
```
ValueError: Item src does not exist.
```
cause A path specified in `autodoc2_packages` does not correspond to an actual directory or module on the file system relative to `conf.py`.

fix Double-check the paths listed in `autodoc2_packages` in your `conf.py`. Ensure they are correct relative paths to your source directories (e.g., `../src/my_package`). Also, verify `sys.path.insert(0, os.path.abspath('../src'))` is correctly pointing to the root where your package resides.
```
Class variable initialized with object: value rendered as None.
```
cause Class variables initialized with complex objects might not have their values correctly extracted and rendered by `sphinx-autodoc2` in version 0.5.0.

fix This appears to be a known issue in version 0.5.0. Check the `sphinx-autodoc2` GitHub repository for updates, bug fixes, or workarounds related to this rendering behavior. You may need to document such variables manually or wait for a patch.

Warnings

breaking Differences from `sphinx.ext.autodoc`: `sphinx-autodoc2` uses static analysis, not dynamic introspection. This means it doesn't execute your code during documentation generation, avoiding side effects but requiring a different mental model for configuration and path resolution.
Fix: Review `sphinx-autodoc2` documentation, especially the 'Differences from `sphinx.ext.autodoc`' section. Configure `autodoc2_packages` with file system paths, not importable module names.
gotcha Encountering 'WARNING: reference target not found' in nitpicky mode, especially for type annotations from external packages.
Fix: This typically means Sphinx cannot resolve cross-references. Ensure external packages are correctly added to your `intersphinx_mapping` in `conf.py`. For renamed or complex types, consider using `autodoc2_replace_annotations` or `autodoc2_replace_bases` options to map them correctly.
gotcha `autodoc2_packages` must not be empty. If this configuration option is unset or empty, `sphinx-autodoc2` will not generate any documentation.
Fix: Ensure `autodoc2_packages` in your `conf.py` is set to a list containing at least one path to a Python package or module. E.g., `autodoc2_packages = ['../src/my_package']`.
breaking The configuration option `autodoc2_replace_annotations` was reported to incorrectly expect a list instead of a dictionary in version 0.5.0, leading to a `Documentation error`.
Fix: Check for updates to `sphinx-autodoc2`. If on 0.5.0, try using a list of dictionaries if a fix is not available, or downgrade if possible. Refer to the official GitHub issues for the latest status and workaround.

Install

pip install sphinx-autodoc2 Install core library
pip install sphinx-autodoc2 myst-parser Install with Markdown support

Imports

autodoc2
```
extensions = ['autodoc2'] # in conf.py
```
sphinx-autodoc2 is enabled as a Sphinx extension, not typically imported directly in Python code for standard usage.

Quickstart

To quickly set up `sphinx-autodoc2`: 1. **Project Structure**: Assume your `conf.py` is in `docs/` and your Python package is in `src/my_package/`. 2. **Install Dependencies**: `pip install sphinx sphinx-autodoc2 myst-parser` (if using Markdown). 3. **Configure `conf.py`**: Add `'autodoc2'` to your `extensions` list and set `autodoc2_packages` to the relative path of your package(s). You might also need to adjust `sys.path` so Sphinx can find your code. If using MyST, add `'myst_parser'` to extensions and optionally set `autodoc2_render_plugin = 'myst'`. 4. **Create API entry point**: In your `index.rst` or `index.md`, include `apidocs/index` in a `toctree` directive. `autodoc2` will generate files in the `apidocs` directory by default.

# docs/conf.py
import os
import sys

# Adjust this path to point to your Python package root relative to conf.py
# Example: if conf.py is in 'docs/' and your package is in 'src/my_package/'
sys.path.insert(0, os.path.abspath('../src'))

project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'

extensions = [
    'sphinx.ext.autodoc', # Often used alongside for other extensions/features
    'myst_parser',        # Required if using Markdown for docstrings or source files
    'autodoc2',           # Enable the sphinx-autodoc2 extension
]

# --- sphinx-autodoc2 configuration ---
# Path(s) to the package(s) you want to document
autodoc2_packages = [
    '../src/my_package', # Replace 'my_package' with your actual package name
]

# Optional: Set the default docstring parser if using Markdown
# autodoc2_render_plugin = 'myst'

# Add your output directory to .gitignore, e.g., 'apidocs/'
# In your index.rst or index.md, add a toctree entry:
#
# .. toctree::
#    :maxdepth: 2
#
#    apidocs/index

view raw JSON →