I am using setuptools to build my sphinx documentation of a python project (python setup.py build_sphinx).
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
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
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.