使用 setuptools 构建 sphinx 文档时如何将警告转化为错误？

Question

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

As found on, eg, this site , I have configured the build process using the setup.cfg:

[build_sphinx]
source-dir = docs/source
build-dir  = docs/build
all_files  = 1

However, I would like to add some more options. Specifically, I would like to turn all warnings into errors, which would work with the sphinx-build command with the option -W :

sphinx-build --help
Sphinx v1.1.3
Usage: /usr/bin/sphinx-build [options] sourcedir outdir [filenames...]
Options: -b <builder> -- builder to use; default is html
         -a        -- write all files; default is to only write new and changed files
         -E        -- don't use a saved environment, always read all files
         -t <tag>  -- include "only" blocks with <tag>
         -d <path> -- path for the cached environment and doctree files
                      (default: outdir/.doctrees)
         -c <path> -- path where configuration file (conf.py) is located
                      (default: same as sourcedir)
         -C        -- use no config file at all, only -D options
         -D <setting=value> -- override a setting in configuration
         -A <name=value>    -- pass a value into the templates, for HTML builder
         -n        -- nit-picky mode, warn about all missing references
         -N        -- do not do colored output
         -q        -- no output on stdout, just warnings on stderr
         -Q        -- no output at all, not even warnings
         -w <file> -- write warnings (and errors) to given file
         -W        -- turn warnings into errors
         -P        -- run Pdb on exception
Modi:
* without -a and without filenames, write new and changed files.
* with -a, write all files.
* with filenames, write these.

I do not see a similar option for python setup.py build_sphinx :

python setup.py build_sphinx --help
Common commands: (see '--help-commands' for more)

  setup.py build      will build the package underneath 'build/'
  setup.py install    will install the package

Global options:
  --verbose (-v)  run verbosely (default)
  --quiet (-q)    run quietly (turns verbosity off)
  --dry-run (-n)  don't actually do anything
  --help (-h)     show detailed help message
  --no-user-cfg   ignore pydistutils.cfg in your home directory

Options for 'BuildDoc' command:
  --fresh-env (-E)   discard saved environment
  --all-files (-a)   build all files
  --source-dir (-s)  Source directory
  --build-dir        Build directory
  --config-dir (-c)  Location of the configuration directory
  --builder (-b)     The builder to use. Defaults to "html"
  --project          The documented project's name
  --version          The short X.Y version
  --release          The full version, including alpha/beta/rc tags
  --today            How to format the current date, used as the replacement
                     for |today|
  --link-index (-i)  Link index.html to the master doc

usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

Does anyone know, if turning all warnings into errors can be achieved when building the sphinx docu with setuptools?

Edit:

The option -W is not recognized by setuptools:

python setup.py build_sphinx -W
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

error: option -W not recognized

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+