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