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

Adicionado na versão 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.

Aviso

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.

Configuração

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.

Por exemplo:

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

Siga os links simbólicos.

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

Por padrão, sphinx-apidoc processa busca sys.path para módulos. Python 3.3 introduziu PEP 420 namespaces implicitos que permitem path e estruturas de módulos como foo/bar/module.py ou foo/bar/baz/__init__.py (perceba que bar e foo são namespaces, não modulos).

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.