sphinx.ext.duration – 测量 Sphinx 处理的持续时间

2.4 版本新增。

此扩展程序测量 Sphinx 在读取文档时的处理持续时间，对于检查哪些文档构建缓慢非常有用。持续时间在构建结束时打印到控制台，并默认保存到输出目录中的 JSON 文件。

通过将 'sphinx.ext.duration' 添加到您 conf.py 文件中的 extensions 列表中来启用此扩展程序

extensions = [
    ...
    'sphinx.ext.duration',
]

配置

duration_print_total
类型:
bool
默认:
True

在构建摘要中显示总读取持续时间，例如：

====================== total reading duration ==========================
Total time reading 31 files: 0m 3.142s

在版本 9.0 中新增。

duration_print_slowest
类型:
bool
默认:
True

在构建摘要中显示最慢的持续时间。持续时间按从最慢到最快的顺序列出。这将打印最多 duration_n_slowest 个持续时间，例如：

====================== slowest 5 reading durations =======================
0.012s spam
0.011s ham
0.011s eggs
0.006s lobster
0.005s beans

在版本 9.0 中新增。

duration_n_slowest
类型:
int
默认:
5

当 duration_print_slowest 启用时，在构建摘要中显示的最慢持续时间的最大数量。默认情况下，只显示最慢的 5 个持续时间。将其设置为 0 以显示所有持续时间。

在版本 9.0 中新增。

duration_write_json
类型:
str | None
默认:
'sphinx-reading-durations.json'

将所有读取持续时间写入输出目录中的 JSON 文件。文件内容是文档名称到读取持续时间的映射，其中文档名称是字符串，持续时间是浮点数（以秒为单位）。将此值设置为空字符串或 None 以禁用写入文件，或将其设置为相对路径以进行自定义。

这对于测试和设置读取时间限制可能很有用。

在版本 9.0 中新增。

duration_limit
类型:
float | int | None
默认:
无

设置读取文档的持续时间限制（以秒为单位）。如果任何持续时间超过此值，则会发出警告。

在版本 9.0 中新增。