{"id":9324,"library":"sphinxcontrib-apidoc","title":"Sphinx Contrib Apidoc","description":"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]","status":"maintenance","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/apidoc","tags":["Sphinx","documentation","API","autodocumentation","apidoc","extension"],"install":[{"cmd":"pip install sphinxcontrib-apidoc","lang":"bash","label":"PyPI"},{"cmd":"conda install sphinxcontrib-apidoc","lang":"bash","label":"Conda-Forge"}],"dependencies":[{"reason":"Core dependency for documentation generation.","package":"Sphinx","optional":false},{"reason":"Relevant for migration from pbr's build_sphinx command, but not a direct runtime dependency.","package":"pbr","optional":true}],"imports":[{"note":"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.","wrong":"import sphinxcontrib.apidoc","symbol":"sphinxcontrib.apidoc","correct":"extensions = ['sphinxcontrib.apidoc']"}],"quickstart":{"code":"import os\nimport sys\n\nsys.path.insert(0, os.path.abspath('.'))\n\n# conf.py in your Sphinx documentation source directory\n\nproject = 'MyProject'\ncopyright = '2023, MyAuthor'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.apidoc'\n]\n\n# --- sphinxcontrib-apidoc specific configuration ---\n# Path to the Python package to document (relative to conf.py)\napidoc_module_dir = '../../my_python_package'\n# Output directory for generated API docs (relative to conf.py)\napidoc_output_dir = 'api_reference'\n# Exclude 'tests' directory from API generation\napidoc_excluded_paths = ['tests']\n# Put documentation for each module on its own page\napidoc_separate_modules = True\n# Filename for a table of contents file (defaults to 'modules')\napidoc_toc_file = 'index'\n# End of sphinxcontrib-apidoc specific configuration ---\n\nhtml_theme = 'alabaster'","lang":"python","description":"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]"},"warnings":[{"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]","message":"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]","severity":"breaking","affected_versions":"0.6.0 (and older) when used with Sphinx 8.2.0+"},{"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`.","message":"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]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Identify and remove the `pbr` related API documentation settings from `setup.cfg` after configuring `sphinxcontrib-apidoc` in `conf.py`.","message":"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]","severity":"gotcha","affected_versions":"All versions, for projects migrating from pbr"},{"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/`.","message":"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]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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]","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]","error":"Extension error: Could not import extension sphinxcontrib.apidoc (exception: No module named 'sphinxcontrib.apidoc')"},{"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::\n   :maxdepth: 2\n\n   autoindex` to `.. toctree::\n   :maxdepth: 2\n\n   api_reference/modules` (assuming `apidoc_output_dir = 'api_reference'`).","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]","error":"WARNING: toctree contains reference to non-existing document u'autoindex'"},{"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.","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.","error":"sphinx-build: error: One or more modules do not exist or can't be imported, or invalid path given for apidoc_module_dir."}]}