1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
#!/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
# 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}
SPHINX_WARNINGS_TRANS=${SPHINX_WARNINGS_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)
function prepare_language_index {
# Global variables
HAS_LANG=0
LANG_INDEX=`mktemp`
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
if [ -f $f.backup ]; then
mv $f.backup $f
fi
done
}
function remove_pot_files {
# remove newly created pot files
rm -f ${DIRECTORY}/source/locale/*.pot
}
function cleanup {
if [ $DOCSTHEME_BUILD_TRANSLATED__NO_CLEANUP ]; then
echo "Skipping cleanup. Your repository is dirty."
return
fi
[ $LANG_INDEX ] && rm -f -- $LANG_INDEX
recover_rst_files
remove_pot_files
}
trap cleanup EXIT
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
# Note that this is the counterpart to how we push
# translations to the server. The code lives in
# https://opendev.org/openstack/openstack-zuul-jobs/src/roles/prepare-zanata-client/files/common_translation_update.sh
# in function extract_messages_doc:
# While Sphinx generates a single pot file per source file in the top
# directory, is generates a file per directory for any subdirectory.
# The function extract_messages_doc creates a file per
# directory, so also for the top directory:
# * For directory X, a file named doc-X.pot is created.
# * All files of the top-level directory are merged into the
# file doc.pot.
# We need to find for each file the downloaded folder file and
# use that to generate translations.
# Case 1: Is this a pot file for a directory and does it have translations?
if [ -e ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/doc-${resname}.po ]; then
msgmerge --silent -o \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/doc-${resname}.po \
${DIRECTORY}/source/locale/${potname}
# Case 2: Is this a a file in the top directory and has translations?
elif [ -e ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/doc.po ]; then
msgmerge --silent -o \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/doc.po \
${DIRECTORY}/source/locale/${potname}
# Otherwise we have no translations for this file, let's create an
# empty po file.
else
msgmerge --silent -o \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po \
${DIRECTORY}/source/locale/${language}/LC_MESSAGES/doc.po \
${DIRECTORY}/source/locale/${potname}
fi
# 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
sphinx-build -a ${SPHINX_BUILD_OPTION_TRANS} -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_pot_files
add_language_index_to_original
# build English document
sphinx-build -a ${SPHINX_BUILD_OPTION_ENG} -b html \
-d ${DIRECTORY}/build/doctrees \
${DIRECTORY}/source ${DIRECTORY}/build/html/
|
