Registry / serialization / sphinx-autodoc2

sphinx-autodoc2

library0.5.0pypypiunverified

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.

serialization

pip install sphinx-autodoc2

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINX-AUTODOC2

sphinx-autodoc2

serializationpythonv0.5.0

Install

4.1s avg

Import

—

Disk

35MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.000s · 99.4MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 4.1s · import 0.000s · 21MB

35MB installed

● package 35MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

autodoc2

✓ extensions = ['autodoc2'] # in conf.py

sphinx-autodoc2 is enabled as a Sphinx extension, not typically imported directly in Python code for standard usage.

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

sphinx-autodoc2 --version

Debug

Known issues

breakingDifferences 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.

affects: All versions

gotchaEncountering '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.

affects: All versions

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']`.

affects: All versions

breakingThe 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.

affects: 0.5.0

Upgrade

Version history

0.5.0latest on PyPI · released Nov 27, 2023

Audit

Dependencies

SphinxrequiredCore dependency for documentation generation framework.

myst-parseroptionalRequired for using Markdown (MyST) docstrings and `.md` source files.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/chrisjsewell/sphinx-autodoc2 ↗

packagehttps://pypi.org/project/sphinx-autodoc2/ ↗