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
This commit is contained in:
Ian Y. Choi 2017-06-06 06:46:06 +00:00 committed by Akihiro Motoki
parent fb172f89ef
commit 412dfb045e
5 changed files with 116 additions and 1 deletions

1
.gitignore vendored
View File

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

View File

@ -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/']

11
tools/add-marker.sh Executable file
View File

@ -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

86
tools/build-docs.sh Executable file
View File

@ -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

16
tox.ini
View File

@ -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 =