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.

(cherry picked from commit 7b6758a)

ticket: 7468
version_fixed: 1.11
status: resolved

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

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