Add options for sphinx-build -W in docstheme-build-translated.sh

The user can choose

- if warnings should be ignored (SKIP_SPHINX_WARNINGS=1)
- if warnings on translation build should be on (SPHINX_WARNINGS_TRANS=1)

added an example to the previously releasenotes

Change-Id: I1486139fdbdef5dd4e00a38c9cb751a5ed7881c6

bin/docstheme-build-translated.sh

@@ -21,6 +21,23 @@ set -x
 DOCNAME=doc
 DIRECTORY=doc
 
+# Sphinx will warnings treated as an error
+SPHINX_BUILD_OPTION_ENG='-W'
+SPHINX_BUILD_OPTION_TRANS='-W'
+
+# Initial env vars
+SKIP_SPHINX_WARNINGS=${SKIP_SPHINX_WARNINGS:-0}
+SKIP_SPHINX_TRANS=${SKIP_SPHINX_TRANS:-0}
+
+# Skip -W option for english and translation builds
+if [ ${SKIP_SPHINX_WARNINGS} -lt 1 ]; then
+    SPHINX_BUILD_OPTION_ENG=''
+fi
+
+if [ ${SPHINX_WARNINGS_TRANS} -gt 0 ]; then
+    SPHINX_BUILD_OPTION_TRANS=''
+fi
+
 # This function sets the following global variables
 # - LANG_INDEX : filename which contains the language index
 # - HAS_LANG : 1 (there are languages other than English), 0 (English only)
@@ -140,8 +157,7 @@ for locale in `find ${DIRECTORY}/source/locale/ -maxdepth 1 -type d` ; do
     done
 
     # build translated guide
-    # TODO(amotoki): Enable -W option in translated version
-    sphinx-build -a -b html -D language=${language} \
+    sphinx-build -a ${SPHINX_BUILD_OPTION_TRANS} -b html -D language=${language} \
         -d ${DIRECTORY}/build/doctrees.languages/${language} \
         ${DIRECTORY}/source ${DIRECTORY}/build/html/${language}
 
@@ -160,7 +176,7 @@ rm -f ${DIRECTORY}/source/locale/*.pot
 add_language_index_to_original
 
 # build English document
-sphinx-build -a -W -b html \
+sphinx-build -a ${SPHINX_BUILD_OPTION_ENG} -b html \
     -d ${DIRECTORY}/build/doctrees \
     ${DIRECTORY}/source ${DIRECTORY}/build/html/
 

releasenotes/notes/add-translations-9238b0f56b677a6b.yaml

@@ -6,3 +6,19 @@ features:
     build translated documents for all languages that exist.
     Invoke ``docstheme-build-translated.sh`` from tox.ini instead of running
     ``sphinx-build`` directly.
+    The following environment variables control the script:
+    ``SKIP_SPHINX_WARNINGS`` to not treat warnings from sphinx-build as an
+    error.
+    ``SPHINX_WARNINGS_TRANS`` will turn on warnings by sphinx-build as
+    an error on translation (use with caution).
+
+    Example for tox.ini:
+
+    ::
+
+      [testenv:docs]
+      deps = -r{toxinidir}/doc/requirements.txt
+      setenv =
+          SKIP_SPHINX_WARNINGS=1
+      commands=
+          docstheme-build-translated.sh