Sphinx

# `sphinx.ext.apidoc` – Generate API documentation from Python packages

Added in version 8.2.

`sphinx.ext.apidoc` is a tool for automatic generation of Sphinx sources from Python packages. It provides the 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 `sphinx.ext.autodoc` extension.

Warning

`sphinx.ext.apidoc` generates source files that use `sphinx.ext.autodoc` to document all found modules. If any modules have side effects on import, these will be executed by `autodoc` when 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:

apidoc_modules
  Type:
    `Sequence[dict[str, str | int | bool | Sequence[str] | Set[str]]`
  Default:
    `()`

  A list or sequence of dictionaries describing modules to document. If a value is left unspecified in any dictionary, the general configuration value is used as the default.

  For example:

      apidoc_modules = [
          {'path': 'path/to/module', 'destination': 'source/'},
          {
              'path': 'path/to/another_module',
              'destination': 'source/',
              'exclude_patterns': ['**/test*'],
              'max_depth': 4,
              'follow_links': False,
              'separate_modules': False,
              'include_private': False,
              'no_headings': False,
              'module_first': False,
              'implicit_namespaces': False,
              'automodule_options': {
                  'members', 'show-inheritance', 'undoc-members'
              },
          },
      ]

  Valid keys are:

  `'path'`

    The path to the module to document (required). This must be absolute or relative to the configuration directory.

  `'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.

  `'exclude_patterns'`

    See `apidoc_exclude_patterns`.

  `'max_depth'`

    See `apidoc_max_depth`.

  `'follow_links'`

    See `apidoc_follow_links`.

  `'separate_modules'`

    See `apidoc_separate_modules`.

  `'include_private'`

    See `apidoc_include_private`.

  `'no_headings'`

    See `apidoc_no_headings`.

  `'module_first'`

    See `apidoc_module_first`.

  `'implicit_namespaces'`

    See `apidoc_implicit_namespaces`.

  `'automodule_options'`

    See `apidoc_automodule_options`.

apidoc_exclude_patterns
  Type:
    `Sequence[str]`
  Default:
    `()`

  A sequence of patterns to exclude from generation. These may be literal paths or `fnmatch`-style patterns.

apidoc_max_depth
  Type:
    `int`
  Default:
    `4`

  The maximum depth of submodules to show in the generated table of contents.

apidoc_follow_links
  Type:
    `bool`
  Default:
    `False`

  Follow symbolic links.

apidoc_separate_modules
  Type:
    `bool`
  Default:
    `False`

  Put documentation for each module on an individual page.

apidoc_include_private
  Type:
    `bool`
  Default:
    `False`

  Generate documentation for ‘_private’ modules with leading underscores.

apidoc_no_headings
  Type:
    `bool`
  Default:
    `False`

  Do not create headings for the modules/packages. Useful when source docstrings already contain headings.

apidoc_module_first
  Type:
    `bool`
  Default:
    `False`

  Place module documentation before submodule documentation.

apidoc_implicit_namespaces
  Type:
    `bool`
  Default:
    `False`

  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.

apidoc_automodule_options
  Type:
    `Set[str]`
  Default:
    `{'members', 'show-inheritance', 'undoc-members'}`

  Options to pass to generated `automodule` directives.