From e04033dec1146548d44d5af6772ba05c21ec5083 Mon Sep 17 00:00:00 2001 From: KATO Tomoyuki Date: Wed, 21 Oct 2015 14:13:28 +0900 Subject: [PATCH] Rework install guide build tool We have two index files for Debian and other distributions. On the other hand, when the tool generates translation resources, uses only one index file, Debian index as of now. Therefore, translation for index files is applied to only one index file. For example, Translation for Ubuntu index file are not applied for Ubuntu Installation Guide. * Unify index files into one file * Process toctree for each distribution dynamically Change-Id: I3abcd7da3569bb8e9edbc02574dcb74c12752ede Closes-Bug: #1507861 --- doc/install-guide/source/conf.py | 9 -- doc/install-guide/source/index-debian.rst | 105 ---------------------- doc/install-guide/source/index.rst | 70 ++++++++++----- tools/build-install-guides-rst.sh | 62 ++++++++++--- 4 files changed, 98 insertions(+), 148 deletions(-) delete mode 100644 doc/install-guide/source/index-debian.rst diff --git a/doc/install-guide/source/conf.py b/doc/install-guide/source/conf.py index c3455dade9..f56f5c0762 100644 --- a/doc/install-guide/source/conf.py +++ b/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. diff --git a/doc/install-guide/source/index-debian.rst b/doc/install-guide/source/index-debian.rst deleted file mode 100644 index 3e3a355f23..0000000000 --- a/doc/install-guide/source/index-debian.rst +++ /dev/null @@ -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` diff --git a/doc/install-guide/source/index.rst b/doc/install-guide/source/index.rst index 18f541a3fb..1a6d20c8b8 100644 --- a/doc/install-guide/source/index.rst +++ b/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,25 +74,57 @@ This guide documents OpenStack Liberty release. Contents ~~~~~~~~ -.. toctree:: - :maxdepth: 2 +.. 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. - common/conventions.rst - overview.rst - environment.rst - keystone.rst - glance.rst - nova.rst - neutron.rst - horizon.rst - cinder.rst - swift.rst - heat.rst - ceilometer.rst - launch-instance.rst +.. only:: obs or rdo or ubuntu - common/app_support.rst - common/glossary.rst + .. toctree:: + :maxdepth: 2 + + common/conventions.rst + overview.rst + environment.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 + +.. 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 ~~~~~~~~~~~~~~~~~~~~ diff --git a/tools/build-install-guides-rst.sh b/tools/build-install-guides-rst.sh index 727b66cdba..6eb226606d 100755 --- a/tools/build-install-guides-rst.sh +++ b/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 | \ - awk '{print substr($0, index($0, "::")+3)}') +# For translation work, we should have only one index file, +# 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}/\" \ - doc/install-guide/source/index.rst" EXIT +# Save and restore the index file +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}/" \ - doc/install-guide/source/index.rst + sed -i -e "s/\.\. title::.*/.. title:: ${title}/" ${INDEX} + + ## + # 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. - if [[ "$tag" == "debian" ]]; then - mv publish-docs/draft/install-guide-debian/index-debian.html \ - publish-docs/draft/install-guide-debian/index.html - fi + # Restore the index file + cp -f ${INDEX}.save ${INDEX} + + ## # Remove Debian specific content from other guides if [[ "$tag" != "debian" ]]; then rm -rf publish-docs/draft/install-guide-$tag/debconf