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.

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.