python-3.x - 在 readthedocs.org 上构建 Sphinx 文档时将所有警告视为错误

Question

我们的开源 Python 项目 ( PyAbel ) 使用 readthedocs.org 使用 Sphinx 为每个拉取请求自动构建文档。如果 Sphinx 有任何警告，我们希望文档构建失败，因为这些通常表明文档的某些部分没有正确构建。

目前，我们包含sphinx: fail_on_warning: true在我们的 .readthedocs.yml 文件中。这会导致 Sphinx 构建在第一次警告时失败。到目前为止，一切都很好！

但是，在我的本地计算机上，我可以使用

make html SPHINXOPTS="-W --keep-going"

允许构建运行完成（从而显示所有警告）然后失败，如此处所述。（或者，我可以包含SPHINXOPTS="-W --keep-going"在 doc/Makefile 中以实现相同的结果。）

这种行为似乎是更好的选择，因为我们可以看到所有需要修复的警告，但构建仍然失败，所以我们知道需要修复它们。但是，当文档建立在 readthedocs.org 上时，我无法弄清楚如何实现这一点。在 readthedocs.org 上构建 Sphinx 文档时，有没有一种方法可以让我们看到来自 Sphinx 构建的所有警告，然后仍然引发错误？

一些相关的讨论是here。

标签： python-3.xpython-sphinxread-the-docs

Answer 1

根据readthedocs 文档，设置fail_on_warning: true当前等同于同时启用-W和--keep-going标志：

sphinx.fail_on_warning

将警告变成错误（-W和--keep-going选项）。这意味着如果出现警告并以退出状态 1 退出，则构建将失败。