From 851ac08dc4e1039a78f658eb7091472931c82404 Mon Sep 17 00:00:00 2001 From: Brian Neradt Date: Fri, 2 Jul 2021 22:02:08 +0000 Subject: [PATCH] Doc build: treat warnings as errors only by default While our English Sphinx docs build without warnings, 20 some warnings are generated from these same source file if translated into Japanese. The warning mechanism for Sphinx seems fragile, therefore. As a compromise, this patch keeps the -W flag (treat warnings as errors) for the default case, but drops that if the user specifies something specific to the SPHINXOPTS. This unblocks other types of builds while still alerting developers of warnings in the default case. --- doc/Makefile.am | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index b0ccf234962..10e6f2f81f1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -44,7 +44,11 @@ endif # BUILD_MANPAGES # see https://media.readthedocs.org/pdf/sphinx/1.6.3/sphinx.pdf # section 24.3.2 around page 247, third item for 'NotImplementedError', so this is kind of useless. -ALLSPHINXOPTS = $(SPHINXOPTS) -W +# Building with errors as warnings is fragile. What works for English may not +# when translated into Japanese, for example. To address this, we have the +# default configuration be to treat warnings as errors, but give up if the user +# passes SPHINXOPTS on the command line. +ALLSPHINXOPTS = $(or $(SPHINXOPTS),-W) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(SPHINXOPTS)