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

Question

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

目前，我们在 .readthedocs.yml 文件中包含

sphinx: fail_on_warning: true

。这会导致 Sphinx 构建在第一次警告时失败。到目前为止，一切都很好！

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

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

允许构建运行完成（从而显示所有警告）然后失败，如此处所述。 （或者，我可以在 doc/Makefile 中包含

SPHINXOPTS="-W --keep-going"

以获得相同的结果。）

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

一些相关的讨论是这里。

Answer 1

根据 readthedocs 文档，设置

fail_on_warning: true

目前相当于启用

-W

和

--keep-going

标志：

sphinx.fail_on_warning

将警告变成错误（

-W

和

--keep-going

选项）。这意味着如果出现警告，构建就会失败并以退出状态 1 退出。

Answer 2

现有答案主要针对 Unix，但不涵盖 Windows。

如果在 Windows 上使用

make.bat

，则必须在两个位置编辑该文件。

首先，添加

SPHINXOPTS

变量，然后修改

sphinx-build

命令的退出行为。

set SOURCEDIR=source
set BUILDDIR=build
set "SPHINXOPTS=-W --keep-going"

...

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% || exit /b %ERRORLEVEL%
goto end

...

在 Unix 上，您只需将

Makefile

行编辑为：

 即可修改 

SPHINXOPTS

SPHINXOPTS    ?= -W --keep-going