Add sphinx.ext.apidoc extension

doc/usage/extensions/apidoc.rst

@@ -0,0 +1,126 @@
+.. _ext-apidoc:
+
+:mod:`sphinx.ext.apidoc` -- Generate API documentation from Python packages
+===========================================================================
+
+.. py:module:: sphinx.ext.apidoc
+   :synopsis: Generate API documentation from Python modules
+
+.. index:: pair: automatic; documentation
+.. index:: pair: generation; documentation
+.. index:: pair: generate; documentation
+
+.. versionadded:: 8.2
+
+.. role:: code-py(code)
+   :language: Python
+
+:mod:`sphinx.ext.apidoc` is a tool for automatic generation
+of Sphinx sources from Python packages.
+It provides the :program:`sphinx-apidoc` command-line tool as an extension,
+allowing it to be run during the Sphinx build process.
+
+The extension writes generated source files to a provided directory,
+which are then read by Sphinx using the :mod:`sphinx.ext.autodoc` extension.
+
+.. warning::
+
+   :mod:`sphinx.ext.apidoc` generates source files that
+   use :mod:`sphinx.ext.autodoc` to document all found modules.
+   If any modules have side effects on import,
+   these will be executed by ``autodoc`` when :program:`sphinx-build` is run.
+
+   If you document scripts (as opposed to library modules),
+   make sure their main routine is protected by
+   an ``if __name__ == '__main__'`` condition.
+
+
+Configuration
+-------------
+
+The apidoc extension uses the following configuration values:
+
+.. confval:: apidoc_modules
+   :no-index:
+   :type: :code-py:`Sequence[dict[str, Any]]`
+   :default: :code-py:`()`
+
+   A list or sequence of dictionaries describing modules to document.
+
+   For example:
+
+   .. code-block:: python
+
+      apidoc_modules = [
+          {'destination': 'source/', 'path': 'path/to/module'},
+          {
+              'destination': 'source/',
+              'path': 'path/to/another_module',
+              'exclude_patterns': ['**/test*'],
+              'maxdepth': 4,
+              'followlinks': False,
+              'separatemodules': False,
+              'includeprivate': False,
+              'noheadings': False,
+              'modulefirst': False,
+              'implicit_namespaces': False,
+              'automodule_options': {
+                  'members', 'show-inheritance', 'undoc-members'
+              },
+          },
+      ]
+
+
+   Valid keys are:
+
+   :code-py:`'destination'`
+     The output directory for generated files (**required**).
+     This must be relative to the source directory,
+     and will be created if it does not exist.
+
+   :code-py:`'path'`
+     The path to the module to document (**required**).
+     This must be absolute or relative to the configuration directory.
+
+   :code-py:`'exclude_patterns'`
+     A sequence of patterns to exclude from generation.
+     These may be literal paths or :py:mod:`fnmatch`-style patterns.
+     Defaults to :code-py:`()`.
+
+   :code-py:`'maxdepth'`
+     The maximum depth of submodules to show in the generated table of contents.
+     Defaults to :code-py:`4`.
+
+   :code-py:`'followlinks'`
+     Follow symbolic links.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'separatemodules'`
+     Put documentation for each module on an individual page.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'includeprivate'`
+     Generate documentation for '_private' modules with leading underscores.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'noheadings'`
+     Do not create headings for the modules/packages.
+     Useful when source docstrings already contain headings.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'modulefirst'`
+     Place module documentation before submodule documentation.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'implicit_namespaces'`
+     By default sphinx-apidoc processes sys.path searching for modules only.
+     Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
+     structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+     (notice that ``bar`` and ``foo`` are namespaces, not modules).
+
+     Interpret module paths using :pep:`420` implicit namespaces.
+     Defaults to :code-py:`False`.
+
+   :code-py:`'automodule_options'`
+     Options to pass to generated :rst:dir:`automodule` directives.
+     Defaults to :code-py:`{'members', 'show-inheritance', 'undoc-members'}`.

doc/usage/extensions/index.rst

@@ -21,6 +21,7 @@ These extensions are built in and can be activated by respective entries in the
 .. toctree::
    :maxdepth: 1
 
+   apidoc
    autodoc
    autosectionlabel
    autosummary

sphinx/ext/apidoc/__init__.py

@@ -13,9 +13,26 @@
 
 from typing import TYPE_CHECKING
 
+import sphinx
 from sphinx.ext.apidoc._cli import main
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
-__all__: Sequence[str] = ('main',)
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+__all__: Sequence[str] = 'main', 'setup'
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    from sphinx.ext.apidoc._extension import run_apidoc
+
+    # Require autodoc
+    app.setup_extension('sphinx.ext.autodoc')
+    app.add_config_value('apidoc_modules', (), 'env', types=frozenset((list, tuple)))
+    app.connect('builder-inited', run_apidoc)
+    return {
+        'version': sphinx.__display_version__,
+        'parallel_read_safe': True,
+    }

sphinx/ext/apidoc/_cli.py

@@ -13,12 +13,8 @@
 import sphinx.locale
 from sphinx import __display_version__
 from sphinx.cmd.quickstart import EXTENSIONS
-from sphinx.ext.apidoc._generate import (
-    ApidocOptions,
-    create_modules_toc_file,
-    recurse_tree,
-)
-from sphinx.ext.apidoc._shared import LOGGER, _remove_old_files
+from sphinx.ext.apidoc._generate import create_modules_toc_file, recurse_tree
+from sphinx.ext.apidoc._shared import LOGGER, ApidocOptions, _remove_old_files
 from sphinx.locale import __
 from sphinx.util.osutil import ensuredir