{"id":8666,"library":"sphinx-autodoc2","title":"Sphinx Autodoc2","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-extensions2/sphinx-autodoc2","tags":["sphinx","documentation","autodoc","api-documentation","static-analysis","markdown","myst"],"install":[{"cmd":"pip install sphinx-autodoc2","lang":"bash","label":"Install core library"},{"cmd":"pip install sphinx-autodoc2 myst-parser","lang":"bash","label":"Install with Markdown support"}],"dependencies":[{"reason":"Core dependency for documentation generation framework.","package":"Sphinx","optional":false},{"reason":"Required for using Markdown (MyST) docstrings and `.md` source files.","package":"myst-parser","optional":true}],"imports":[{"note":"sphinx-autodoc2 is enabled as a Sphinx extension, not typically imported directly in Python code for standard usage.","symbol":"autodoc2","correct":"extensions = ['autodoc2'] # in conf.py"}],"quickstart":{"code":"# docs/conf.py\nimport os\nimport sys\n\n# Adjust this path to point to your Python package root relative to conf.py\n# Example: if conf.py is in 'docs/' and your package is in 'src/my_package/'\nsys.path.insert(0, os.path.abspath('../src'))\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nrelease = '0.1.0'\n\nextensions = [\n    'sphinx.ext.autodoc', # Often used alongside for other extensions/features\n    'myst_parser',        # Required if using Markdown for docstrings or source files\n    'autodoc2',           # Enable the sphinx-autodoc2 extension\n]\n\n# --- sphinx-autodoc2 configuration ---\n# Path(s) to the package(s) you want to document\nautodoc2_packages = [\n    '../src/my_package', # Replace 'my_package' with your actual package name\n]\n\n# Optional: Set the default docstring parser if using Markdown\n# autodoc2_render_plugin = 'myst'\n\n# Add your output directory to .gitignore, e.g., 'apidocs/'\n# In your index.rst or index.md, add a toctree entry:\n#\n# .. toctree::\n#    :maxdepth: 2\n#\n#    apidocs/index\n","lang":"python","description":"To quickly set up `sphinx-autodoc2`:\n\n1.  **Project Structure**: Assume your `conf.py` is in `docs/` and your Python package is in `src/my_package/`.\n2.  **Install Dependencies**: `pip install sphinx sphinx-autodoc2 myst-parser` (if using Markdown).\n3.  **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'`.\n4.  **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."},"warnings":[{"fix":"Review `sphinx-autodoc2` documentation, especially the 'Differences from `sphinx.ext.autodoc`' section. Configure `autodoc2_packages` with file system paths, not importable module names.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"Encountering 'WARNING: reference target not found' in nitpicky mode, especially for type annotations from external packages.","severity":"gotcha","affected_versions":"All versions"},{"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']`.","message":"`autodoc2_packages` must not be empty. If this configuration option is unset or empty, `sphinx-autodoc2` will not generate any documentation.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"0.5.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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']`.","cause":"The `autodoc2_packages` list in `conf.py` is either missing or empty.","error":"WARNING: autodoc2_packages must not be empty [autodoc2.config_error]"},{"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`.","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.","error":"WARNING: <filename>.rst:<line_number>: WARNING: reference target not found: <SomeType>"},{"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.","cause":"A path specified in `autodoc2_packages` does not correspond to an actual directory or module on the file system relative to `conf.py`.","error":"ValueError: Item src does not exist."},{"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.","cause":"Class variables initialized with complex objects might not have their values correctly extracted and rendered by `sphinx-autodoc2` in version 0.5.0.","error":"Class variable initialized with object: value rendered as None."}]}