sphinx.ext.apidoc -- 利用 Python 包产生 API 文档

在 8.2 版本加入.

sphinx.ext.apidoc 是自动为Python包产生Sphinx源码(rst)的工具。该扩展提供 sphinx-apidoc 命令行，允许在Sphinx构建期间运行它。

此扩展将产生的源码文件写到提供的目录内，然后由Sphinx使用 sphinx.ext.autodoc 扩展读取。

警告

由 sphinx.ext.apidoc 产生的源码文件被 sphinx.ext.autodoc 使用，来为python模块生成文档。若在导入时有任何模块具有副作用，这些副作用将在运行 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 （注意这里的 foo 和 bar 都用来表示命名空间，并不是模块）。

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

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

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