{"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":"python","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,"search_vec":"'0.6.0':45 '1':78 '8.2.0':54 '9':79 'api':26,36,82 'apidoc':3,6,20,84 'autodocument':83 'autom':13 'build':23 'built':60 'built-in':59 'contrib':2 'current':42 'design':11 'document':27,37,81 'encourag':70 'extens':10,62,76,85 'function':65 'generat':25 'includ':57 'instead':77 'integr':34 'mainten':50 'mode':51 'nativ':74 'new':67 'newer':56 'offer':63 'packag':30 'process':15 'project':40,47 'python':29 'run':17 'similar':64 'sphinx':1,9,19,39,53,75,80 'sphinx-apidoc':18 'sphinxcontrib':5 'sphinxcontrib-apidoc':4 'streamlin':32 'therebi':24 'use':72 'user':68 'version':43","created_at":"2026-04-16T18:49:37.414955+00:00","updated_at":"2026-04-16T18:49:37.414955+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sphinx-contrib/apidoc","docs":null,"changelog":null,"pypi":"https://pypi.org/project/sphinxcontrib-apidoc/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}