Sphinx Contrib Apidoc

0.6.0 · maintenance · verified Thu Apr 16

sphinxcontrib-apidoc is a Sphinx extension designed to automate the process of running `sphinx-apidoc` on each build, thereby generating API documentation from Python packages. It streamlines the integration of API documentation into Sphinx projects. The current version is 0.6.0. This project is in maintenance mode, as Sphinx 8.2.0 and newer include a built-in extension offering similar functionality, and new users are encouraged to use the native Sphinx extension instead. [1, 9]

Common errors

```
Extension error: Could not import extension sphinxcontrib.apidoc (exception: No module named 'sphinxcontrib.apidoc')
```
cause The `sphinxcontrib-apidoc` package is not installed in the Python environment where Sphinx is being run, or the environment is not correctly activated/configured (e.g., in a pre-commit hook). [16]

fix Install the package using `pip install sphinxcontrib-apidoc` in the active environment. If using a `pre-commit` hook, ensure `additional_dependencies` includes `sphinxcontrib-apidoc`. [16]
```
WARNING: toctree contains reference to non-existing document u'autoindex'
```
cause `sphinxcontrib-apidoc` (and standalone `sphinx-apidoc`) generates its main table of contents file as `modules.rst` by default, not `autoindex.rst` as might be expected from other `autodoc` setups. [1, 4, 9]

fix Change the reference in your main `index.rst` (or other relevant `toctree`) from `autoindex` to `modules` (or the value configured for `apidoc_toc_file`). For example, change `.. toctree:: :maxdepth: 2 autoindex` to `.. toctree:: :maxdepth: 2 api_reference/modules` (assuming `apidoc_output_dir = 'api_reference'`).
```
sphinx-build: error: One or more modules do not exist or can't be imported, or invalid path given for apidoc_module_dir.
```
cause The path specified in `apidoc_module_dir` in `conf.py` does not correctly point to a discoverable Python package, or the package itself has issues preventing its import.

fix Verify that `apidoc_module_dir` is correctly set as a path relative to `conf.py` and points to the root of your Python package (e.g., `../my_package`). Ensure `__init__.py` files are present in your package and subpackages, and the package can be imported successfully in a standard Python interpreter.

Warnings

breaking Sphinx 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]
Fix: Migrate 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]
gotcha The 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]
Fix: Update 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`.
gotcha When 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]
Fix: Identify and remove the `pbr` related API documentation settings from `setup.cfg` after configuring `sphinxcontrib-apidoc` in `conf.py`.
gotcha The `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]
Fix: Ensure `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/`.

Install

pip install sphinxcontrib-apidoc PyPI
conda install sphinxcontrib-apidoc Conda-Forge

Imports

sphinxcontrib.apidoc
wrong:
```
import sphinxcontrib.apidoc
```
correct:
```
extensions = ['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.

Quickstart

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'

view raw JSON →