sphinx.ext.coverage – 收集文档覆盖率统计信息¶
此扩展功能增加了一个额外的构建器，即 CoverageBuilder。
注意
sphinx-apidoc 命令可用于自动为项目中的所有代码生成 API 文档，从而避免手动编写这些文档并保持更新的需求。
警告
coverage **导入** 要记录的模块。如果任何模块在导入时具有副作用，则在运行 sphinx-build 时，覆盖率构建器将执行这些副作用。
如果您记录脚本（而不是库模块），请确保它们的主例程受到 if __name__ == '__main__' 条件的保护。
注意
为了让 Sphinx（实际上是执行 Sphinx 的 Python 解释器）找到您的模块，它必须是可导入的。这意味着模块或包必须位于 sys.path 上的目录之一中 – 相应地在配置文件中调整您的 sys.path。
要使用此构建器，请在您的配置文件中激活 coverage 扩展，并在命令行上运行 sphinx-build -M coverage。
构建器¶
配置¶
可以使用多个配置值来指定构建器应检查的内容
- coverage_modules¶
- 类型:
Sequence[str]- 默认值:
()
要测试覆盖率的 Python 包或模块的列表。当提供此列表时，Sphinx 将内省此列表中提供的每个包或模块，以及在每个包中找到的所有子包和子模块。当未提供此列表时，Sphinx 将仅为它知道的 Python 包和模块提供覆盖率：即，使用
py:module指令（在 Python 域 中提供）或automodule指令（由autodoc扩展提供）记录的任何模块。7.4 版本新增。
- coverage_ignore_modules¶
- coverage_ignore_functions¶
- coverage_ignore_classes¶
- coverage_ignore_pyobjects¶
- 类型:
Sequence[str]- 默认值:
()
Python 正则表达式列表。
如果这些正则表达式中的任何一个与 Python 对象的完整导入路径的任何部分匹配，则该 Python 对象将从文档覆盖率报告中排除。
2.1 版本新增。
- coverage_c_path¶
- 类型:
Sequence[str]- 默认值:
()
- coverage_c_regexes¶
- 类型:
dict[str, str]- 默认值:
{}
- coverage_ignore_c_items¶
- 类型:
dict[str, Sequence[str]]- 默认值:
{}
- coverage_write_headline¶
- 类型:
布尔值- 默认值:
True
设置为
False以不写入标题。1.1 版本新增。
- coverage_skip_undoc_in_source¶
- 类型:
布尔值- 默认值:
False
跳过在源代码中没有使用文档字符串记录的对象。
1.1 版本新增。
- coverage_show_missing_items¶
- 类型:
布尔值- 默认值:
False
同时将缺少对象打印到标准输出。
3.1 版本新增。
- coverage_statistics_to_report¶
- 类型:
布尔值- 默认值:
True
将覆盖率统计信息的表格报告打印到覆盖率报告中。
示例输出
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
7.2 版本新增。
- coverage_statistics_to_stdout¶
- 类型:
布尔值- 默认值:
False
将覆盖率统计信息的表格报告打印到标准输出。
示例输出
+-----------------------+----------+--------------+ | Module | Coverage | Undocumented | +=======================+==========+==============+ | package.foo_module | 100.00% | 0 | +-----------------------+----------+--------------+ | package.bar_module | 83.33% | 1 | +-----------------------+----------+--------------+
7.2 版本新增。