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

Question

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

正如在本网站上找到的那样,我使用setup.cfg配置了构建过程:

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

但是,我想补充一些选项.具体来说,我想将所有警告转换为错误,这可以使用sphinx-build带有选项的命令-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.

我没有看到类似的选项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文档时,是否可以将所有警告转换为错误？

编辑:

-Wsetuptools无法识别该选项:

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

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

make html SPHINXOPTS="-W"

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

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

有关选项列表，请参见此处。

Answer 2

在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 1.5+，请参见stephenfin的答案