sphinx.ext.apidoc – 从 Python 包生成 API 文档

在 8.2 版本中添加。

sphinx.ext.apidoc 是一个用于从 Python 包自动生成 Sphinx 源文件的工具。它提供了 sphinx-apidoc 命令行工具作为扩展，允许在 Sphinx 构建过程中运行它。

此扩展将生成的源文件写入提供的目录，然后 Sphinx 使用 sphinx.ext.autodoc 扩展读取这些文件。

警告

sphinx.ext.apidoc 生成使用 sphinx.ext.autodoc 来文档化所有找到的模块的源文件。如果任何模块在导入时具有副作用，当运行 sphinx-build 时，这些副作用将由 autodoc 执行。

如果您要文档化脚本（而不是库模块），请确保它们的主例程受到 if __name__ == '__main__' 条件的保护。

配置

apidoc 扩展使用以下配置值

apidoc_modules
类型:
Sequence[dict[str, str | int | bool | Sequence[str] | Set[str]]
默认值:
()

描述要文档化的模块的字典的列表或序列。如果在任何字典中未指定值，则通用配置值将用作默认值。

例如

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'

要文档化的模块的路径（必需）。这必须是绝对路径或相对于配置目录的路径。

'destination'

生成文件的输出目录（必需）。这必须是相对于源目录的路径，如果不存在，则将创建它。

'exclude_patterns'

请参阅 apidoc_exclude_patterns。

'max_depth'

请参阅 apidoc_max_depth。

'follow_links'

请参阅 apidoc_follow_links。

'separate_modules'

请参阅 apidoc_separate_modules。

'include_private'

请参阅 apidoc_include_private。

'no_headings'

请参阅 apidoc_no_headings。

'module_first'

请参阅 apidoc_module_first。

'implicit_namespaces'

请参阅 apidoc_implicit_namespaces。

'automodule_options'

请参阅 apidoc_automodule_options。

apidoc_exclude_patterns
类型:
Sequence[str]
默认值:
()

要从生成中排除的模式序列。这些可以是文字路径或 fnmatch 风格的模式。

apidoc_max_depth
类型:
int
默认值:
4

要在生成的目录表中显示的最大子模块深度。

类型:
bool
默认值:
False

跟踪符号链接。

apidoc_separate_modules
类型:
bool
默认值:
False

将每个模块的文档放在单独的页面上。

apidoc_include_private
类型:
bool
默认值:
False

为带有前导下划线的 “_private” 模块生成文档。

apidoc_no_headings
类型:
bool
默认值:
False

不为模块/包创建标题。当源文档字符串已包含标题时很有用。

apidoc_module_first
类型:
bool
默认值:
False

将模块文档放在子模块文档之前。

apidoc_implicit_namespaces
类型:
bool
默认值:
False

默认情况下，sphinx-apidoc 仅处理 sys.path 搜索模块。Python 3.3 引入了 PEP 420 隐式命名空间，它允许模块路径结构，例如 foo/bar/module.py 或 foo/bar/baz/__init__.py（请注意，bar 和 foo 是命名空间，而不是模块）。

使用 PEP 420 隐式命名空间解释模块路径。

apidoc_automodule_options
类型:
Set[str]
默认值:
{'members', 'show-inheritance', 'undoc-members'}

传递给生成的 automodule 指令的选项。