CODEWITHSUNDEEP
python-3.xpython-sphinxread-the-docs
DanHickstein
DanHickstein

Reputation: 6948

See all warnings as errors when building Sphinx docs on readthedocs.org

Our open-source Python project (PyAbel) uses readthedocs.org to automatically build the documentation for each pull request using Sphinx. We would like the doc build to fail if there are any warnings from Sphinx, since these usually indicate that some part of the documentation isn't building correctly.

Currently, we are including sphinx: fail_on_warning: true in our .readthedocs.yml file. This causes the Sphinx build to fail on the first warning. So far, so good!

However, on my local computer, I can use 

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

to allow the build to run to completion (thereby showing all the warnings) and then fail, as discussed here. (Alternatively, I can include SPHINXOPTS="-W --keep-going" in the doc/Makefile to achieve the same result.)

This behavior seems like the better option, since we get to see all of the warnings that we need to fix, and the build still fails, so we know that we need to fix them. But, I cannot figure out how to achieve this when the documentation is built on readthedocs.org. While building Sphinx docs on readthedocs.org is there a way that we can see all the warnings from the Sphinx build and then still raise an error?

Some related discussion is here.

Upvotes: 3

Views: 1883

Answers (2)

ReenigneArcher
ReenigneArcher

Reputation: 135

The existing answer focuses on Unix, but does not cover Windows.

If using the make.bat on Windows, you must edit the file in two places.

First, adding the SPHINXOPTS variable, then modifying the exit behavior of the sphinx-build command.

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

...

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

...

Upvotes: 0

jakevdp
jakevdp

Reputation: 86443

According to the readthedocs documentation, setting fail_on_warning: true is currently equivalent to enabling both the -W and --keep-going flags:

sphinx.fail_on_warning

Turn warnings into errors (-W and --keep-going options). This means the build fails if there is a warning and exits with exit status 1.

Upvotes: 1

Related Questions