Question

我使用setuptools来构建python项目的sphinx文档（python setup.py build_sphinx）。

如在this site上找到的那样，我使用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文档时，是否可以将所有警告转换为错误？

编辑：

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

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

更改自：

python setup.py build_sphinx

为：

python -W error setup.py build_sphinx

这会将所有警告变成错误，包括来自setuptools等的错误，这些错误并不完全符合您的要求，但将停止在sphinx上错误。

如果你这样做是为了尝试设置持续集成或其他什么，也许这还不错？

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

Answer 2

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

make html SPHINXOPTS="-W"

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

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

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

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

2 个答案: