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.

警告

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.

設定

The apidoc extension uses the following configuration values:

apidoc_modules
タイプ:
Sequence[dict[str, str | int | bool | Sequence[str] | Set[str]]
デフォルト:
()

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.

例:

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'
        },
    },
]

有効なキー:

'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
タイプ:
Sequence[str]
デフォルト:
()

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

apidoc_max_depth
タイプ:
int
デフォルト:
4

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

タイプ:
bool
デフォルト:
False

シンボリックリンクを辿ります。

apidoc_separate_modules
タイプ:
bool
デフォルト:
False

各モジュールのドキュメントを独立したページに配置します。

apidoc_include_private
タイプ:
bool
デフォルト:
False

Generate documentation for '_private' modules with leading underscores.

apidoc_no_headings
タイプ:
bool
デフォルト:
False

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

apidoc_module_first
タイプ:
bool
デフォルト:
False

サブモジュールのドキュメントの前に、モジュールのドキュメントを配置します。

apidoc_implicit_namespaces
タイプ:
bool
デフォルト:
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
タイプ:
Set[str]
デフォルト:
{'members', 'show-inheritance', 'undoc-members'}

Options to pass to generated automodule directives.