使用 setuptools 构建 sphinx 文档时如何将警告变成错误？

Question

我正在使用 setuptools 构建我的 python 项目 (python setup.py build_sphinx) 的 sphinx 文档。

如在 this site 上找到的，我已经使用 setup.cfg 配置了构建过程：

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

但是，我想添加更多选项。具体来说，我想将所有警告转换为错误，这将与带有选项-W 的sphinx-build 命令一起使用：

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.

我没有看到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

有谁知道，在使用 setuptools 构建 sphinx 文档时是否可以将所有警告变成错误？

编辑：

setuptools 无法识别选项-W：

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

如果相反，像我一样，您使用 make 使用 Sphinx 构建您的 html 文档，那么您可以这样做将警告变成错误并导致 make 失败：

make html SPHINXOPTS="-W"

当遇到警告时，这将导致构建立即失败。如果您添加--keep-going，则文档构建仍然会失败，但它会运行到完成，因此您可以看到所有警告。 -n 将调用 'nit-picky' 选项来检查损坏的链接。因此，在我的 CI 框架中构建文档时，我发现这很有用：

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

有关选项列表，请参阅 here。

Answer 2

在recent versions of Sphinx 中，您可以通过向setup.cfg 中的部分添加一个附加选项来做到这一点：

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

Sphinx 1.5 中添加了对此的支持，因此，这不适用于旧版本。

Answer 3

我能管理的唯一解决方案既简单又不理想。

更改自：

python setup.py build_sphinx

到：

python -W error setup.py build_sphinx

这会将所有警告变成错误，包括来自 setuptools 等的错误，这不是您想要的，但它会在 sphinx 错误时停止。

如果您这样做是为了尝试设置持续集成或其他东西，也许这已经足够了？

更新：如果使用 Sphinx 1.5+，请参阅 stephenfin's answer