Make sphinx warnings fatal for doc build

We currently do not have any warnings.  Let us keep it that way by
making warnings fatal in maintainer-mode (and configurable on the
buildslaves).  Using sphinx-build -W also causes errors to be reported
in the exit status and picked up by make, which is quite useful.

In order to allow the build bot to use -W but end-users to not use it,
SPHINX_ARGS must be passed on the command line; it cannot be set by
the convenience target 'htmlsrc'.  Document this.

ticket: 7468 (new)
tags: pullup
target_version: 1.11

diff --git a/doc/build_this.rst b/doc/build_this.rst
index 4177f58ddbc9ce2589556a90ad67e78ac87fa932..d31ee232bcc822573b486fd7efd5fda23b8d69d3 100644 (file)
--- a/doc/build_this.rst
+++ b/doc/build_this.rst
@@ -62,7 +62,7 @@ paths.
 You can also do this from an unconfigured source tree with::
 
     cd src/doc
-    make -f Makefile.in htmlsrc
+    make -f Makefile.in SPHINX_ARGS= htmlsrc
 
 
 Building for an OS package or site documentation

diff --git a/src/doc/Makefile.in b/src/doc/Makefile.in
index 1d977284aaa9697222d4b7c5fa220dd3c8f4cdc4..1986f8f7cbd6563caab38b32acb4a61b29b9e881 100644 (file)
--- a/src/doc/Makefile.in
+++ b/src/doc/Makefile.in
@@ -1,7 +1,8 @@
 mydir=doc
 BUILDTOP=$(REL)..
 
-SPHINX_BUILD=sphinx-build
+SPHINX_ARGS=@MAINT@-W
+SPHINX_BUILD=sphinx-build $(SPHINX_ARGS)
 DOXYGEN=doxygen
 
 docsrc=$(top_srcdir)/../doc
@@ -37,7 +38,7 @@ LATEXOPTS=
 # release tarball or the web site (that is, without substitutions for
 # configured paths).  This can be done in an unconfigured source tree
 # as:
-#     make -f Makefile.in htmlsrc
+#     make -f Makefile.in SPHINX_ARGS= htmlsrc
 html: composite
        rm -rf $(docsrc)/html
        $(SPHINX_BUILD) -q rst_composite $(docsrc)/html