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.