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

Added in version 8.2.

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

扩展将生成的源文件写入提供的目录，然后Sphinx使用 sphinx.ext.autodoc 扩展名.

警告

sphinx.ext.apidoc 生成使用 sphinx.ext.autodoc 记录所有找到的模块。如果任何模块对导入有副作用，则将由以下人员执行 autodoc 当 sphinx-build 就是跑步。

如果您记录脚本（与库模块相对），请确保它们的主例程受到 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'

要记录的模块的路径（ required ).这必须是绝对的或相对于配置目录的。

'destination'

生成的文件的输出目录（ required ).这必须相对于源目录，如果源目录不存在，将创建该目录。

'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

默认情况下，phinx-apidoc仅处理sys.路径搜索模块。引入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 指令。