使用 setuptools 构建 sphinx 文档时如何将警告转化为错误? [英] How to turn warnings into errors when building sphinx documentation with setuptools?
问题描述
我正在使用 setuptools 来构建 Python 项目的 sphinx 文档(python setup.py build_sphinx).
I am using setuptools to build my sphinx documentation of a python project (python setup.py build_sphinx).
如在本网站上找到的那样，我已经使用 setup.cfg 配置了构建过程:
As found on, e.g., 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
但是，我想添加更多选项.具体来说，我想将所有警告转换为错误，这将与带有选项 -W 的 sphinx-build 命令一起使用:
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.
我没有看到 python setup.py build_sphinx 的类似选项:
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
有谁知道，使用setuptools构建sphinx文档时是否可以将所有警告转化为错误?
Does anyone know, if turning all warnings into errors can be achieved when building the sphinx docu with setuptools?
setuptools 无法识别选项 -W:
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
推荐答案
在 Sphinx 的最新版本，您可以通过向 setup.cfg 中的部分添加一个附加选项来实现:
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
在 Sphinx 1.5 中添加了对此的支持，因此，这不会使用旧版本.
Support for this was added in Sphinx 1.5, thus, this will not work with older versions.
这篇关于使用 setuptools 构建 sphinx 文档时如何将警告转化为错误?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
