generatepot-rst: dedicate logic to generate common-rst.pot

Previously common-rst.pot is additive only and
deleted strings in the source document will remain forever.
This commit make generatepot-rst.sh not reuse existing
common-rst.pot and generate the POT file from scratch.

This patch creates an index rst file which includes all
files under common-rst and generate common-rst.pot.
By doing so, all contents of common-rst can be covered.

Closes-Bug: #1507138
Change-Id: I888f37ad5e14a0e1cc7d182e376acaf63f98e565

doc/common-rst/source/conf.py

@@ -0,0 +1,122 @@
+# 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.
+
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+# import sys
+
+
+import openstackdocstheme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder'
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Common documents'
+bug_tag = u'common-rst'
+
+copyright = u'2015, OpenStack contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0.0'
+
+# A few variables have to be set for the log-a-bug feature.
+#   giturl: The location of conf.py on Git. Must be set manually.
+#   gitsha: The SHA checksum of the bug description. Automatically extracted from git log.
+#   bug_tag: Tag for categorizing the bug. Must be set manually.
+# These variables are passed to the logabug code via html_context.
+giturl = u'http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/common-rst/source'
+git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
+gitsha = os.popen(git_cmd).read().strip('\n')
+html_context = {"gitsha": gitsha, "bug_tag": bug_tag,
+                "giturl": giturl}
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# -- Options for Internationalization output ------------------------------
+locale_dirs = ['locale/']

tools/generatepot-rst.sh

@@ -35,10 +35,23 @@ else
     NUMBER_OF_CORES=2
 fi
 
-# We're not doing anything for this directory. But we need to handle
+# common-rst is imported from various RST documents, but what files are
-# it by this script so that the common-rst.pot file gets registered.
+# used varies across RST documents. Thus we need an index file to include
-if [[ "$DOCNAME" = "common-rst" ]] ; then
+# all files under common-rst. To this aim, we create such document called
-    exit 0
+# 'common-rst-work' dynamically to generate the POT file of common-rst.
+if [[ "$REPOSITORY" = "openstack-manuals" && "$DOCNAME" = "common-rst" ]] ; then
+    DIRECTORY="doc/common-rst-work"
+    TOPDIR="doc/"
+    mkdir -p $DIRECTORY/source
+    cp doc/common-rst/source/conf.py $DIRECTORY/source/conf.py
+    ln -sf ../../common-rst $DIRECTORY/source/common
+    cat <<EOF > $DIRECTORY/source/index.rst
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   common/*
+EOF
 fi
 
 if [ "$REPOSITORY" = "openstack-manuals" ] ; then
@@ -56,58 +69,30 @@ if [ ${DOCNAME} = "install-guide" ] ; then
     TAG="-t obs -t rdo -t ubuntu -t debian"
 fi
 if [ ${DOCNAME} = "firstapp" ] ; then
-    TAG="-t libcloud  -t dotnet -t fog -t pkgcloud -t shade"
+    TAG="-t libcloud -t dotnet -t fog -t pkgcloud -t shade"
 fi
 sphinx-build -j $NUMBER_OF_CORES -b gettext $TAG ${DIRECTORY}/source/ \
     ${DIRECTORY}/source/locale/
 
-if [ "$REPOSITORY" = "openstack-manuals" ] ; then
+if [[ "$REPOSITORY" = "openstack-manuals" && "$DOCNAME" = "common-rst" ]] ; then
-    # Update common
+    # In case of common-rst, we use the working directory 'common-rst-work'.
-    sed -i -e 's/^"Project-Id-Version: [a-zA-Z0-9\. ]+\\n"$/"Project-Id-Version: \\n"/' \
+    # Copies the generated POT to common-rst/source/locale
-        ${DIRECTORY}/source/locale/common.pot
+    # and finally removes the working directory.
-    # Create the common pot file
+    msgcat ${DIRECTORY}/source/locale/common.pot | \
-    msgcat --sort-by-file ${TOPDIR}common-rst/source/locale/common-rst.pot \
+        awk '$0 !~ /^\# [a-z0-9]+$/' \
-        ${DIRECTORY}/source/locale/common.pot | \
+        > ${TOPDIR}common-rst/source/locale/common-rst.pot
-        sed -e 's/^"Project-Id-Version: [a-zA-Z0-9\. ]+\\n"$/"Project-Id-Version: \\n"/' | \
+    rm -rf $DIRECTORY
-        awk '$0 !~ /^\# [a-z0-9]+$/' | awk '$0 !~ /^\# \#-\#-\#-\#-\# /' \
-        > ${DIRECTORY}/source/locale/common-rst.pot
-    mv -f ${DIRECTORY}/source/locale/common-rst.pot \
-        ${TOPDIR}common-rst/source/locale/common-rst.pot
-    rm -f ${DIRECTORY}/source/locale/common.pot
-
-    # Simplify metadata
-    rm -f ${TOPDIR}common-rst/source/locale/dummy.po
-    cat << EOF > ${TOPDIR}common-rst/source/locale/dummy.po
-msgid ""
-msgstr ""
-"Project-Id-Version: \n"
-"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2015-01-01 01:01+0900\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-EOF
-    msgmerge -N ${TOPDIR}common-rst/source/locale/dummy.po \
-        ${TOPDIR}common-rst/source/locale/common-rst.pot \
-        > ${TOPDIR}common-rst/source/locale/tmp.pot
-    mv -f ${TOPDIR}common-rst/source/locale/tmp.pot \
-        ${TOPDIR}common-rst/source/locale/common-rst.pot
-    rm -f ${TOPDIR}common-rst/source/locale/dummy.po
 else
     # common-rst is translated as part of openstack-manuals, do not
     # include the file in the combined tree if it exists.
     rm -f ${DIRECTORY}/source/locale/common.pot
+    # Take care of deleting all temporary files so that
+    # "git add ${DIRECTORY}/source/locale" will only add the
+    # single pot file.
+    # Remove UUIDs, those are not necessary and change too often
+    msgcat --sort-by-file ${DIRECTORY}/source/locale/*.pot | \
+        awk '$0 !~ /^\# [a-z0-9]+$/' > ${DIRECTORY}/source/$DOCNAME.pot
+    rm  ${DIRECTORY}/source/locale/*.pot
+    rm -rf ${DIRECTORY}/source/locale/.doctrees/
+    mv ${DIRECTORY}/source/$DOCNAME.pot ${DIRECTORY}/source/locale/$DOCNAME.pot
 fi
-
-# Take care of deleting all temporary files so that
-# "git add ${DIRECTORY}/source/locale" will only add the
-# single pot file.
-# Remove UUIDs, those are not necessary and change too often
-msgcat --sort-by-file ${DIRECTORY}/source/locale/*.pot | \
-  awk '$0 !~ /^\# [a-z0-9]+$/' > ${DIRECTORY}/source/$DOCNAME.pot
-rm  ${DIRECTORY}/source/locale/*.pot
-rm -rf ${DIRECTORY}/source/locale/.doctrees/
-mv ${DIRECTORY}/source/$DOCNAME.pot ${DIRECTORY}/source/locale/$DOCNAME.pot