How to turn warnings into errors when building sphinx documentation with setuptools?

Question

I am using setuptools to build my sphinx documentation of a python project (python setup.py build_sphinx).

As found on, e.g., this site, I have configured t

Answer 1

If instead, like me, you're using make to build your html docs with Sphinx, then you can do this to turn warnings into errors and cause make to fail:

make html SPHINXOPTS="-W"

This will cause the build to fail immediately when a warning is encountered. If you add --keep-going then the docs build will still fail but it will run to completion so you can see all the warnings. And -n will invoke the 'nit-picky' option to check for broken links. So I find this useful when building the docs in my CI framework:

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

See here for a list of options.

Answer 2

In recent versions of Sphinx, you do this by adding an additional option to the section in setup.cfg:

[build_sphinx]
all-files = 1
source-dir = docs/source
build-dir = docs/build
warning-is-error = 1

Support for this was added in Sphinx 1.5, thus, this will not work with older versions.

Answer 3

The only solution I can manage is both simple and sub-optimal.

Change from:

python setup.py build_sphinx

to:

python -W error setup.py build_sphinx

That will turn all warnings into errors, including errors from setuptools, etc., which isn't exactly what you want, but it will stop on sphinx errors.

If you're doing this to try and set up Continuous Integration or something, maybe this is good enough?

UPDATE: See stephenfin's answer if using Sphinx 1.5+