Install & Compatibility
Where this runs
tested against v0.6.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 93.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.6s · import 0.000s · 94MB
99MB installed
● package 99MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.apidoc
✓ extensions = ['sphinxcontrib.apidoc']
✗ import sphinxcontrib.apidoc
This library is a Sphinx extension, not a module to be directly imported into Python code. It is activated by adding its name to the 'extensions' list in Sphinx's conf.py file.
To quickly integrate `sphinxcontrib-apidoc`, first ensure it's installed. Then, edit your Sphinx `conf.py` file to add `'sphinxcontrib.apidoc'` to your `extensions` list. Crucially, configure `apidoc_module_dir` to point to the root of your Python package, relative to `conf.py`. You should also specify `apidoc_output_dir` for where the generated reStructuredText files will reside, and optionally, `apidoc_excluded_paths` to skip unwanted modules or directories. Finally, include the generated TOC file (e.g., 'api_reference/index') in your main documentation's `toctree`. [9]
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
# conf.py in your Sphinx documentation source directory
project = 'MyProject'
copyright = '2023, MyAuthor'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinxcontrib.apidoc'
]
# --- sphinxcontrib-apidoc specific configuration ---
# Path to the Python package to document (relative to conf.py)
apidoc_module_dir = '../../my_python_package'
# Output directory for generated API docs (relative to conf.py)
apidoc_output_dir = 'api_reference'
# Exclude 'tests' directory from API generation
apidoc_excluded_paths = ['tests']
# Put documentation for each module on its own page
apidoc_separate_modules = True
# Filename for a table of contents file (defaults to 'modules')
apidoc_toc_file = 'index'
# End of sphinxcontrib-apidoc specific configuration ---
html_theme = 'alabaster'
Debug
Known issues
breakingSphinx 8.2.0 introduced a built-in `sphinx.ext.apidoc` extension that provides similar functionality. `sphinxcontrib-apidoc` will eventually be retired. New users should prioritize the built-in extension, and existing users are strongly encouraged to migrate. [1, 9, 10]fixMigrate to `sphinx.ext.apidoc`. Refer to the `sphinxcontrib-apidoc` GitHub README for a migration guide. This typically involves removing `sphinxcontrib.apidoc` from `extensions` and configuring `sphinx.ext.apidoc` settings in `conf.py` instead. [1]
affects: 0.6.0 (and older) when used with Sphinx 8.2.0+
gotchaThe extension generates a table of contents file named `modules.rst` (or `apidoc_toc_file` if configured) by default, not `autoindex.rst`. References in your main documentation (e.g., in `index.rst`) must be updated accordingly. [1, 4, 9]fixUpdate any `.. toctree::` directives in your Sphinx documentation to reference `modules.rst` or your custom `apidoc_toc_file` (e.g., `api_reference/modules` or `api_reference/index`) instead of `autoindex.rst`.
affects: All versions
gotchaWhen migrating from `pbr`'s `build_sphinx` command, specific settings like `autodoc_index_modules`, `autodoc_exclude_modules`, and `api_doc_dir` must be removed from the `[pbr]` section of `setup.cfg` to avoid conflicts. [1, 4, 9]fixIdentify and remove the `pbr` related API documentation settings from `setup.cfg` after configuring `sphinxcontrib-apidoc` in `conf.py`.
affects: All versions, for projects migrating from pbr
gotchaThe `apidoc_module_dir` setting in `conf.py` *must* point to your actual Python package directory, not the top-level repository directory. Failing to do so can lead to `setup.py` and other unrelated files being included in the documentation. [4, 9]fixEnsure `apidoc_module_dir` is set to the correct path of your Python package, e.g., `../my_package_name` if `conf.py` is in `docs/` and your package is in `my_package_name/`.
affects: All versions
Upgrade
Version history
0.6.0latest on PyPI · released May 8, 2025
Audit
Dependencies
SphinxrequiredCore dependency for documentation generation.
pbroptionalRelevant for migration from pbr's build_sphinx command, but not a direct runtime dependency.