Merge "Rework install guide build tool"

doc/install-guide/source/conf.py

@@ -53,11 +53,6 @@ source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
-# We need to use noqa here since tags is defined externally.
-if tags.has('debian'):  # noqa
-    master_doc = 'index-debian'
-else:
-    master_doc = 'index'
 
 # General information about the project.
 project = u'Installation Guide'
@@ -99,10 +94,6 @@ html_context = {"gitsha": gitsha, "bug_tag": bug_tag,
 exclude_patterns = ['common/cli*', 'common/nova*',
                     'common/log_in_dashboard.rst',
                     'shared/note_configuration_vary_by_distribution.rst']
-if tags.has('debian'):  # noqa
-    exclude_patterns.append('index.rst')
-else:
-    exclude_patterns.append('index-debian.rst')
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

doc/install-guide/source/index-debian.rst

@@ -1,105 +0,0 @@
-=======================================
-OpenStack Installation Guide for Debian
-=======================================
-
-.. Be aware that index-debian and index need to have the same content
-   so that translations work. Only the strings from the file
-   index-debian gets send to our translation server.
-
-.. only:: rdo
-
-   ====================================================================
-   OpenStack Installation Guide for Red Hat Enterprise Linux and CentOS
-   ====================================================================
-
-.. only:: obs
-
-   ===================================================================
-   OpenStack Installation Guide for openSUSE and SUSE Linux Enterprise
-   ===================================================================
-
-.. only:: ubuntu
-
-   =======================================
-   OpenStack Installation Guide for Ubuntu
-   =======================================
-
-.. only:: debian
-
-   =======================================
-   OpenStack Installation Guide for Debian
-   =======================================
-
-
-Abstract
-~~~~~~~~
-
-The OpenStack system consists of several key projects that you install
-separately. These projects work together depending on your cloud
-needs. These projects include Compute, Identity Service, Networking,
-Image Service, Block Storage, Object Storage, Telemetry,
-Orchestration, and Database. You can install any of these projects
-separately and configure them stand-alone or as connected entities.
-
-.. only:: rdo
-
-   This guide shows you how to install OpenStack by using packages
-   available on Red Hat Enterprise Linux 7 and its derivatives through
-   the EPEL repository.
-
-.. only:: ubuntu
-
-   This guide walks through an installation by using packages
-   available through Canonical's Ubuntu Cloud archive repository.
-
-.. only:: obs
-
-   This guide shows you how to install OpenStack by using packages on
-   openSUSE 13.2 and SUSE Linux Enterprise Server 12 through the Open
-   Build Service Cloud repository.
-
-.. only:: debian
-
-   This guide walks through an installation by using packages
-   available through Debian 8 (code name: Jessie).
-
-Explanations of configuration options and sample configuration files
-are included.
-
-This guide documents OpenStack Liberty release.
-
-.. warning::
-
-   This guide is a work-in-progress and is subject to frequent updates.
-   Pre-release packages have been used for testing, and some instructions
-   might not work with final versions. Please help us make this guide better
-   by reporting any errors you encounter.
-
-Contents
-~~~~~~~~
-
-.. toctree::
-   :maxdepth: 2
-
-   common/conventions.rst
-   overview.rst
-   environment.rst
-   debconf/debconf.rst
-   keystone.rst
-   glance.rst
-   nova.rst
-   neutron.rst
-   horizon.rst
-   cinder.rst
-   swift.rst
-   heat.rst
-   ceilometer.rst
-   launch-instance.rst
-
-   common/app_support.rst
-   common/glossary.rst
-
-Search in this guide
-~~~~~~~~~~~~~~~~~~~~
-
-* :ref:`search`

doc/install-guide/source/index.rst

@@ -2,10 +2,6 @@
 
 .. Don't remove or change title tag manually, which is used by the build tool.
 
-.. Be aware that index-debian and index need to have the same content
-   so that translations work. Only the strings from the file
-   index-debian gets send to our translation server.
-
 .. only:: rdo
 
    ====================================================================
@@ -78,7 +74,14 @@ This guide documents OpenStack Liberty release.
 Contents
 ~~~~~~~~
 
-.. toctree::
+.. Pseudo only directive for each distribution used by the build tool.
+   This pseudo only directive for toctree only works fine with Tox.
+   When you directly build this guide with Sphinx,
+   some navigation menu may not work properly.
+
+.. only:: obs or rdo or ubuntu
+
+   .. toctree::
       :maxdepth: 2
 
       common/conventions.rst
@@ -98,6 +101,31 @@ Contents
       common/app_support.rst
       common/glossary.rst
 
+.. only:: debian
+
+   .. toctree::
+      :maxdepth: 2
+
+      common/conventions.rst
+      overview.rst
+      environment.rst
+      debconf/debconf.rst
+      keystone.rst
+      glance.rst
+      nova.rst
+      neutron.rst
+      horizon.rst
+      cinder.rst
+      swift.rst
+      heat.rst
+      ceilometer.rst
+      launch-instance.rst
+
+      common/app_support.rst
+      common/glossary.rst
+
+.. end of contents
+
 Search in this guide
 ~~~~~~~~~~~~~~~~~~~~
 

tools/build-install-guides-rst.sh

@@ -3,6 +3,7 @@
 mkdir -p publish-docs
 
 TAGS=${1:-obs rdo ubuntu debian}
+INDEX=doc/install-guide/source/index.rst
 
 LINKCHECK=""
 if [[ $# > 0 ]] ; then
@@ -11,31 +12,66 @@ if [[ $# > 0 ]] ; then
     fi
 fi
 
-title_org=$(grep "title::" doc/install-guide/source/index.rst | \
+# For translation work, we should have only one index file,
-              awk '{print substr($0, index($0, "::")+3)}')
+# 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.
 
-trap "sed -i -e \"s/\.\. title::.*/.. title:: ${title_org}/\" \
+# Save and restore the index file
-  doc/install-guide/source/index.rst" EXIT
+cp -f ${INDEX} ${INDEX}.save
+trap "mv -f ${INDEX}.save ${INDEX}" EXIT
 
 for tag in $TAGS; do
     GLOSSARY=""
     if [[ ! -e doc/common-rst/glossary.rst ]] ; then
         GLOSSARY="--glossary"
     fi
-    title=$(grep -m 1 -A 5 ".. only:: ${tag}" \
+
-              doc/install-guide/source/index.rst | \
+    ##
+    # 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/install-guide/source/index.rst
+
+    ##
+    # 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
     tools/build-rst.sh doc/install-guide  \
         $GLOSSARY --tag ${tag} --target "draft/install-guide-${tag}" \
         $LINKCHECK
 
-    # Debian uses index-debian, rename it.
+    # Restore the index file
-    if [[ "$tag" == "debian" ]]; then
+    cp -f ${INDEX}.save ${INDEX}
-        mv publish-docs/draft/install-guide-debian/index-debian.html \
+
-            publish-docs/draft/install-guide-debian/index.html
+    ##
-    fi
     # Remove Debian specific content from other guides
     if [[ "$tag" != "debian" ]]; then
         rm -rf publish-docs/draft/install-guide-$tag/debconf