Publish translated guides with publishdocs tox job

This patch proposes to publish translated I18n contributor guide(s)
using publishdocs tox job.

It assumes that the URL structure of translated guides would follow
https://docs.openstack.org/developer/i18n/[language-code] scheme.

publishdocs tox job first executes docs job
which builds the original guide, then it executes build-docs.sh
build-docs.sh shell script which outputs
translated I18n contributor guide(s) into [language-code] directory
from current docs job output directory.
Then it copies to publish-docs/developer/i18n directory including
translated guide(s). The directory will be synced through
infra jenkins job which is implemented later.

Note that specifying locale directory in conf.py is needed
to enable sphinx-build execution with locale files.

Implements: blueprint i18n-guide-translation
Co-Authored-By: Akihiro Motoki <amotoki@gmail.com>
Change-Id: Id117308190de56bf9a9c4eb712bda82dea6f9e51

.gitignore

@@ -1,4 +1,5 @@
 /doc/build/
+/publish-docs/
 /openstacki18n.egg-info/
 AUTHORS
 ChangeLog

doc/source/conf.py

@@ -218,3 +218,6 @@ htmlhelp_basename = 'i18n-contributor-guide'
 
 # If true, publish source files
 html_copy_source = False
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ['locale/']

tools/add-marker.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+if [[ $# != 1 ]] ; then
+   echo "Pass directory to add marker to as single paramter"
+   exit 1
+fi
+
+# This marker is needed for infra publishing
+MARKER_TEXT="Project: $ZUUL_PROJECT Ref: $ZUUL_REFNAME Build: $ZUUL_UUID"
+
+echo $MARKER_TEXT > $1/.root-marker

tools/build-docs.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+# Build English and translated version of the I18n guide.
+
+set -e
+
+DOCNAME=doc
+DIRECTORY=doc
+
+if [ -x "$(command -v getconf)" ]; then
+    NUMBER_OF_CORES=$(getconf _NPROCESSORS_ONLN)
+else
+    NUMBER_OF_CORES=2
+fi
+
+# build i18n contributor guide page index.html
+sphinx-build -a -W -j $NUMBER_OF_CORES -b html \
+    -d ${DIRECTORY}/build/doctrees \
+    ${DIRECTORY}/source ${DIRECTORY}/build/html/
+
+if [ "${NO_LANG_BUILD:-0}" = "1" ]; then
+    exit 0
+fi
+
+sphinx-build -a -W -j $NUMBER_OF_CORES -b gettext \
+    -d ${DIRECTORY}/build/doctrees.gettext \
+    ${DIRECTORY}/source ${DIRECTORY}/source/locale/
+
+# check all language translation resouce
+for locale in `find ${DIRECTORY}/source/locale/ -maxdepth 1 -type d` ; do
+    # skip if it is not a valid language translation resource.
+    if [ ! -e ${locale}/LC_MESSAGES/${DOCNAME}.po ]; then
+        continue
+    fi
+    language=$(basename $locale)
+
+    echo "===== Building $language translation ====="
+
+    # prepare all translation resources
+    for pot in ${DIRECTORY}/source/locale/*.pot ; do
+        # get filename
+        potname=$(basename $pot)
+        resname=${potname%.pot}
+        echo $resname
+        # merge all translation resources
+        msgmerge --silent -o \
+            ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po \
+            ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po \
+            ${DIRECTORY}/source/locale/${potname}
+        # compile all translation resources
+        msgfmt -o \
+            ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.mo \
+            ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po
+    done
+
+    # build translated guide
+    # build i18n contributor guide page index.html
+    # TODO(amotoki): Enable -W option in translated version
+    sphinx-build -a -j $NUMBER_OF_CORES -b html -D language=${language} \
+        -d ${DIRECTORY}/build/doctrees.languages/${language} \
+        ${DIRECTORY}/source ${DIRECTORY}/build/html/${language}
+
+    # remove newly created files
+    git clean -f -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/*.po
+    git clean -f -x -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/*.mo
+    git clean -f -x -q ${DIRECTORY}/source/locale/.doctrees
+    # revert changes to po file
+    git reset -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po
+    git checkout -- ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po
+done
+
+# remove newly created pot files
+rm -f ${DIRECTORY}/source/locale/*.pot

tox.ini

@@ -14,7 +14,21 @@ deps = -r{toxinidir}/requirements.txt
 commands = {posargs}
 
 [testenv:docs]
-commands = sphinx-build -W -b html doc/source doc/build/html
+passenv =
+  # Required by add-marker.sh
+  ZUUL*
+  # Pass NO_LANG_BUILD=1 if you would like to build English version only
+  NO_LANG_BUILD
+commands =
+  # Build translated guides
+  {toxinidir}/tools/build-docs.sh
+  # Publish
+  mkdir -p publish-docs/developer/i18n
+  rsync -av --delete doc/build/html/ publish-docs/developer/i18n/
+  {toxinidir}/tools/add-marker.sh publish-docs/developer/i18n/
+whitelist_externals =
+  mkdir
+  rsync
 
 [testenv:pep8]
 commands =