Merge "Rework install guide translation build tool"

bin/doc-tools-check-languages

@@ -97,31 +97,70 @@ function build_rst {
         done
     elif [ ${book} = "install-guide" ] ; then
         # Install Guide has several variations, build all of them
-        title_org=$(grep "title::" ${DOC_DIR}${book}/source/index.rst | \
+        TAGS="obs rdo ubuntu debian"
-                awk '{print substr($0, index($0, "::")+3)}')
+        INDEX=${DOC_DIR}${book}/source/index.rst
 
-        trap "sed -i -e \"s/\.\. title::.*/.. title:: ${title_org}/\" \
+        # For translation work, we should have only one index file,
-                ${DOC_DIR}${book}/source/index.rst" EXIT
+        # because our tools generate translation resources from
+        # only one index file.
+        # Therefore, this tool uses one combined index file
+        # while processing title and toctree for each distribution.
 
-        for tag in obs rdo ubuntu debian; do
+        # Save and restore the index file
-            title=$(grep -m 1 -A 5 ".. only:: ${tag}" \
+        cp -f ${INDEX} ${INDEX}.save
-                ${DOC_DIR}${book}/source/index.rst | \
+        trap "mv -f ${INDEX}.save ${INDEX}" EXIT
+
+        for tag in $TAGS; do
+            ##
+            # Because Sphinx uses the first heading as title regardless of
+            # only directive, replace title directive with the proper title
+            # for each distribution to set the title explicitly.
+            title=$(grep -m 1 -A 5 "^.. only:: ${tag}" ${INDEX} | \
                 sed -n 4p | sed -e 's/^ *//g')
-            sed -i -e "s/\.\. title::.*/.. title:: ${title}/" \
+            sed -i -e "s/\.\. title::.*/.. title:: ${title}/" ${INDEX}
-                ${DOC_DIR}${book}/source/index.rst
+
-            tox -evenv "sphinx-build -j $NUMBER_OF_CORES -q -E -t $tag -D language=${language} \
+            ##
-                ${DOC_DIR}${book}/source/ \
+            # Sphinx builds the navigation before processing directives,
+            # so the conditional toctree does not work.
+            # We need to prepare toctree depending on distribution
+            # only with one toctree before exectuing sphinx-build.
+
+            # Get line number of each tag
+            lineno_start=$(grep -n "^Contents" ${INDEX} | sed -e 's/:.*//')
+            lineno_end=$(grep -n "^.. end of contents" ${INDEX} | sed -e 's/:.*//')
+            lineno_debian=$(grep -n "^.. only:: debian" ${INDEX} \
+                | tail -1 | sed -e 's/:.*//')
+            lineno_notdebian=$(grep -n "^.. only:: [^d]" ${INDEX} \
+                | tail -1 | sed -e 's/:.*//')
+
+            # Remove indent for pseudo only directive
+            sed -i "${lineno_start},${lineno_end} s/^  *\.\. toctree/.. toctree/" ${INDEX}
+            sed -i "${lineno_start},${lineno_end} s/^  */   /" ${INDEX}
+
+            # Remove unnecessary toctree for each distribution
+            if [[ "$tag" == "debian" ]]; then
+                sed -i "${lineno_notdebian},${lineno_debian}d" ${INDEX}
+            else
+                sed -i "${lineno_debian},$((${lineno_end}-1))d" ${INDEX}
+                sed -i "${lineno_notdebian}d" ${INDEX}
+            fi
+
+            # Build the guide
+            tox -evenv "sphinx-build -j $NUMBER_OF_CORES -q -E -t $tag \
+                -D language=${language} ${DOC_DIR}${book}/source/ \
                 ${DOC_DIR}${book}/build-${tag}/html"
             mkdir -p publish-docs/${language}/${book}-${tag}
             rsync -a ${DOC_DIR}${book}/build-${tag}/html/ \
                 publish-docs/${language}/${book}-${tag}
+
+            # Restore the index file
+            cp -f ${INDEX}.save ${INDEX}
+
+            # Remove Debian specific content from other guides
+            if [[ "$tag" != "debian" ]]; then
+                rm -rf publish-docs/${language}/{book}-$tag/debconf
+            fi
         done
-        # Debian Install Guide uses index-debian, we need to rename the file
-        INSTALL_DEBIAN="publish-docs/${language}/install-guide-debian/"
-        if [ -f ${INSTALL_DEBIAN}/index-debian.html ] ; then
-            mv ${INSTALL_DEBIAN}/index-debian.html \
-                ${INSTALL_DEBIAN}/index.html
-        fi
     else
         tox -evenv "sphinx-build -j $NUMBER_OF_CORES -q -E -D language=${language} \
             ${DOC_DIR}${book}/source/ \

releasenotes/notes/rework-install-guide-d50130d9a7189009.yaml

@@ -0,0 +1,4 @@
+---
+fixes:
+  - Rework install guide translation build tool
+    to process toctree for each distribution dynamically.