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