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
This commit is contained in:
KATO Tomoyuki
parent
daf50f7774
commit
e04033dec1
@ -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.
|
||||
|
||||
@ -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`
|
||||
@ -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,6 +74,13 @@ This guide documents OpenStack Liberty release.
|
||||
Contents
|
||||
~~~~~~~~
|
||||
|
||||
.. 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
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user