Import tools for building translated documents

Import from i18n repo the scripts get-lang-display-name.py and
build-docs.sh, update comments so that they are generic.

Add the two files to setup.cfg so that they get distributed with the
package and can be executed from tox for building of translated
documents.

Change-Id: I80fcb1ed857da8452b310e6707cce3940577a35a
This commit is contained in:
Andreas Jaeger 2018-11-24 17:39:43 +01:00
parent 98c23d2b84
commit 0948c2dc65
4 changed files with 206 additions and 0 deletions

167
bin/docstheme-build-translated.sh Executable file
View File

@ -0,0 +1,167 @@
#!/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 an RST document
set -e
set -x
DOCNAME=doc
DIRECTORY=doc
# 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)
function prepare_language_index {
# Global variables
HAS_LANG=0
LANG_INDEX=`mktemp`
trap "rm -f -- $LANG_INDEX" EXIT
cat <<EOF >> $LANG_INDEX
[
\`English <__BASE__/__INDEX__>\`__
EOF
# Generate language index file
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)
# Reference translated document from index file
echo -n "| " >> $LANG_INDEX
HAS_LANG=1
get_lang_name_prog=$(dirname $0)/docstheme-lang-display-name.py
name=`python3 $get_lang_name_prog $language`
echo "\`$name <__BASE__/${language}/__INDEX__>\`__" >> $LANG_INDEX
done
cat <<EOF >> $LANG_INDEX
]
EOF
}
function _add_language_index {
local target_file=$1
local basepath=$2
local basename
basename=$(echo $target_file | sed -e "s|$DIRECTORY/source/||" -e "s|\.rst$||")
path_to_top_level=$(dirname $basename | sed -e 's|[^./]\+|..|g')
local _basepath
if [ "$basepath" = "." -a "$path_to_top_level" = "." ]; then
_basepath="."
elif [ "$basepath" = "." ]; then
_basepath=$path_to_top_level
elif [ "$path_to_top_level" = "." ]; then
_basepath=$basepath
else
_basepath="$basepath/$path_to_top_level"
fi
cp -p $target_file $target_file.backup
sed -e "s|__BASE__|$_basepath|" -e "s|__INDEX__|$basename.html|" $LANG_INDEX > $target_file
cat $target_file.backup >> $target_file
}
function add_language_index_to_localized {
for f in `find $DIRECTORY/source -name '*.rst'`; do
_add_language_index $f ..
done
}
function add_language_index_to_original {
for f in `find $DIRECTORY/source -name '*.rst'`; do
cp -p $f.backup $f
_add_language_index $REFERENCES $f .
done
}
function recover_rst_files {
for f in `find $DIRECTORY/source -name '*.rst'`; do
mv $f.backup $f
done
}
sphinx-build -a -W -b gettext \
-d ${DIRECTORY}/build/doctrees.gettext \
${DIRECTORY}/source ${DIRECTORY}/source/locale/
prepare_language_index
if [ "$HAS_LANG" = "0" ]; then
exit 0
fi
# Now add our references to the beginning of the index file. We cannot do this
# earlier since the sphinx commands will read this file.
# Ensure to revert any changes to the index file.
add_language_index_to_localized
# check all language translation resource
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}
# 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
# TODO(amotoki): Enable -W option in translated version
sphinx-build -a -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 -q -- ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po
done
# remove newly created pot files
rm -f ${DIRECTORY}/source/locale/*.pot
add_language_index_to_original
# build English document
sphinx-build -a -W -b html \
-d ${DIRECTORY}/build/doctrees \
${DIRECTORY}/source ${DIRECTORY}/build/html/
recover_rst_files

View File

@ -0,0 +1,28 @@
#!/usr/bin/env python
#
# 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.
import sys
import babel
# Print full name of short language code, e.g.
# returns "Deutsch" for "de".
lang_code = sys.argv[1]
try:
l = babel.Locale.parse(lang_code)
print(l.get_display_name())
except Exception:
print(lang_code)

View File

@ -0,0 +1,8 @@
---
features:
- |
Add tools for building translated documents. The file
``docstheme-build-translated.sh`` will look for translations and
build translated documents for all languages that exist.
Invoke ``docstheme-build-translated.sh`` from tox.ini instead of running
``sphinx-build`` directly.

View File

@ -26,6 +26,9 @@ setup-hooks =
[files]
packages =
openstackdocstheme
scripts =
bin/docstheme-build-translated.sh
bin/docstheme-lang-display-name.py
[build_sphinx]
all_files = 1