openstack/openstack-manuals
Code Issues Proposed changes

Merge "[install] remove Debian specific procedure from tool"

Browse Source
This commit is contained in:
Jenkins 2016-05-25 14:39:44 +00:00 committed by Gerrit Code Review
commit 96a8a0c71f
16 changed files with 62 additions and 605 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/install-guide/source/ceilometer-install.rst
View File

@ -205,8 +205,8 @@ Install and configure components
.. only:: debian .. only:: debian
Respond to prompts for Respond to prompts for debconf.
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, .. :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

4
doc/install-guide/source/cinder-controller-install.rst
View File

@ -249,8 +249,8 @@ Install and configure components
.. only:: debian .. only:: debian
Respond to prompts for Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`, .. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

101
doc/install-guide/source/debconf/debconf-api-endpoints.rst
View File

@ -1,101 +0,0 @@
:orphan:
======================
Register API endpoints
======================
All Debian packages for API services, except the ``heat-api`` package,
register the service in the Identity service catalog. This feature is
helpful because API endpoints are difficult to remember.
.. note::
The ``heat-common`` package and not the ``heat-api`` package configures the
Orchestration service.
When you install a package for an API service, you are prompted to
register that service. However, after you install or upgrade the package
for an API service, Debian immediately removes your response to this
prompt from the debconf database. Consequently, you are prompted to
re-register the service with the Identity service. If you already
registered the API service, respond ``no`` when you upgrade.
.. image:: ../figures/debconf-screenshots/api-endpoint_1_register_endpoint.png
|
This screen registers packages in the Identity service catalog:
.. image:: ../figures/debconf-screenshots/api-endpoint_2_keystone_server_ip.png
|
You are prompted for the Identity service ``admin_token`` value. The
Identity service uses this value to register the API service. When you
set up the ``keystone`` package, this value is configured automatically.
.. image:: ../figures/debconf-screenshots/api-endpoint_3_keystone_authtoken.png
|
This screen configures the IP addresses for the service. The
configuration script automatically detects the IP address used by the
interface that is connected to the default route (``/sbin/route`` and
``/sbin/ip``).
Unless you have a unique set up for your network, press **ENTER**.
.. image:: ../figures/debconf-screenshots/api-endpoint_4_service_endpoint_ip_address.png
|
This screen configures the region name for the service. For example,
``us-east-coast`` or ``europe-paris``.
.. image:: ../figures/debconf-screenshots/api-endpoint_5_region_name.png
|
The Debian package post installation scripts will then perform the below
commands for you:
.. code-block:: console
# openstack --os-token ${AUTH_TOKEN} \
--os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \
--os-domain-name default \
--os-identity-api-version=3 \
service create \
--name=${SERVICE_NAME} \
--description="${SERVICE_DESC}" \
${SERVICE_TYPE}
# openstack --os-token ${AUTH_TOKEN} \
--os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \
--os-domain-name default \
--os-identity-api-version=3 \
endpoint create \
--region "${REGION_NAME}" \
${SERVICE_NAME} public http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL}
# openstack --os-token ${AUTH_TOKEN} \
--os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \
--os-domain-name default \
--os-identity-api-version=3 \
endpoint create \
--region "${REGION_NAME}" \
${SERVICE_NAME} internal http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL}
# openstack --os-token ${AUTH_TOKEN} \
--os-url=http://${KEYSTONE_ENDPOINT_IP}:35357/v3/ \
--os-domain-name default \
--os-identity-api-version=3 \
endpoint create \
--region "${REGION_NAME}" \
${SERVICE_NAME} admin http://${PKG_ENDPOINT_IP}:${SERVICE_PORT}${SERVICE_URL}
The values of ``AUTH_TOKEN``, ``KEYSTONE_ENDPOINT_IP``,
``PKG_ENDPOINT_IP``, and ``REGION_NAME`` depend on the answer you will
provide to the debconf prompts. But the values of ``SERVICE_NAME``,
``SERVICE_TYPE``, ``SERVICE_DESC``, and ``SERVICE_URL`` are already
pre-wired in each package, so you don't have to remember them.

120
doc/install-guide/source/debconf/debconf-concepts.rst
View File

@ -1,120 +0,0 @@
:orphan:
================
debconf concepts
================
This chapter explains how to use the Debian ``debconf`` and
``dbconfig-common`` packages to configure OpenStack services. These
packages enable users to perform configuration tasks. When users
install OpenStack packages, ``debconf`` prompts the user for responses,
which seed the contents of configuration files associated with that package.
After package installation, users can update the configuration of a
package by using the :command:`dpkg-reconfigure` program.
If you are familiar with these packages and pre-seeding, you can proceed
to :doc:`../keystone`.
The Debian packages
-------------------
The rules described here are from the `Debian Policy
Manual <http://www.debian.org/doc/debian-policy/>`__. If any rule
described in this chapter is not respected, you have found a serious bug
that must be fixed.
When you install or upgrade a Debian package, all configuration file
values are preserved. Using the ``debconf`` database as a registry is
considered a bug in Debian. If you edit something in any OpenStack
configuration file, the ``debconf`` package reads that value when it
prepares to prompt the user. For example, to change the log in name for
the RabbitMQ messaging queue for a service, you can edit its value in
the corresponding configuration file.
To opt out of using the ``debconf`` package, run the
:command:`dpkg-reconfigure` command and select non-interactive mode:
.. code-block:: console
# dpkg-reconfigure -plow debconf
Then, ``debconf`` does not prompt you.
Another way to disable the ``debconf`` package is to prefix the
:command:`apt` command with ``DEBIAN_FRONTEND=noninteractive``,
as follows:
.. code-block:: console
# DEBIAN_FRONTEND=noninteractive apt-get install nova-api
If you configure a package with ``debconf`` incorrectly, you can
re-configure it, as follows:
.. code-block:: console
# dpkg-reconfigure PACKAGE-NAME
This calls the post-installation script for the ``PACKAGE-NAME`` package
after the user responds to all prompts. If you cannot install a Debian
package in a non-interactive way, you have found a release-critical bug
in Debian. Report it to the Debian bug tracking system.
Generally, the ``-common`` packages install the configuration files. For
example, the ``glance-common`` package installs the ``glance-api.conf``
and ``glance-registry.conf`` files. So, for the Image service, you must
re-configure the ``glance-common`` package. The same applies for
``cinder-common``, ``nova-common``, and ``heat-common`` packages.
In ``debconf``, the higher the priority for a screen, the greater the
chance that the user sees that screen. If a ``debconf`` screen has
``medium`` priority and you configure the Debian system to show only
``critical`` prompts, which is the default in Debian, the user does not
see that ``debconf`` screen. Instead, the default for the related package
is used. In the Debian OpenStack packages, a number of ``debconf`` screens
are set with ``medium`` priority. Consequently, if you want to respond to
all ``debconf`` screens from the Debian OpenStack packages, you must run
the following command and select the ``medium`` priority before you install
any packages:
.. code-block:: console
# dpkg-reconfigure debconf
.. note::
The packages do not require pre-depends. If ``dbconfig-common`` is
already installed on the system, the user sees all prompts. However,
you cannot define the order in which the ``debconf`` screens appear.
The user must make sense of it even if the prompts appear in an
illogical order.
|
Pre-seed debconf prompts
------------------------
You can pre-seed all ``debconf`` prompts. To pre-seed means to store
responses in the ``debconf`` database so that ``debconf`` does not prompt
the user for responses. Pre-seeding enables a hands-free installation for
users. The package maintainer creates scripts that automatically
configure the services.
The following example shows how to pre-seed an automated MySQL Server
installation:
.. code-block:: bash
MYSQL_PASSWORD=MYSQL_PASSWORD
echo "mysql-server-5.5 mysql-server/root_password password ${MYSQL_PASSWORD}
mysql-server-5.5 mysql-server/root_password seen true
mysql-server-5.5 mysql-server/root_password_again password ${MYSQL_PASSWORD}
mysql-server-5.5 mysql-server/root_password_again seen true
" | debconf-set-selections
DEBIAN_FRONTEND=noninteractive apt-get install -y --force-yes mysql-server
The ``seen true`` option tells ``debconf`` that a specified screen was
already seen by the user so do not show it again. This option is useful
for upgrades.

167
doc/install-guide/source/debconf/debconf-dbconfig-common.rst
View File

@ -1,167 +0,0 @@
:orphan:
===========================================
Configure the database with dbconfig-common
===========================================
Many of the OpenStack services need to be configured to access a
database. These are configured through a DSN (Database Source Name)
directive as follows:
.. code-block:: ini
[database]
connection = mysql+pymysql://keystone:0dec658e3f14a7d@localhost/keystonedb
This ``connection`` directive will be handled by the ``dbconfig-common``
package, which provides a standard Debian interface. It enables you to
configure Debian database parameters. It includes localized prompts for
many languages and it supports the following database backends: SQLite,
MySQL, and PostgreSQL.
By default, the ``dbconfig-common`` package configures the OpenStack
services to use SQLite. So if you use debconf in non-interactive mode
and without pre-seeding, the OpenStack services that you install will
use SQLite.
By default, ``dbconfig-common`` does not provide access to database servers
over a network. If you want the ``dbconfig-common`` package to prompt for
remote database servers that are accessed over a network and not through
a UNIX socket file, reconfigure it, as follows:
.. code-block:: console
# apt-get install dbconfig-common && dpkg-reconfigure dbconfig-common
These screens appear when you re-configure the ``dbconfig-common`` package:
.. image:: ../figures/debconf-screenshots/dbconfig-common_keep_admin_pass.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_used_for_remote_db.png
|
Unlike other debconf prompts, you cannot pre-seed the responses for the
``dbconfig-common`` prompts by using ``debconf-set-selections``. Instead,
you must create a file in :file:`/etc/dbconfig-common`. For example, you
might create a keystone configuration file for ``dbconfig-common`` that is
located in :file:`/etc/dbconfig-common/keystone.conf`, as follows:
.. code-block:: ini
dbc_install='true'
dbc_upgrade='true'
dbc_remove=''
dbc_dbtype='mysql'
dbc_dbuser='keystone'
dbc_dbpass='PASSWORD'
dbc_dbserver=''
dbc_dbport=''
dbc_dbname='keystonedb'
dbc_dbadmin='root'
dbc_basepath=''
dbc_ssl=''
dbc_authmethod_admin=''
dbc_authmethod_user=''
After you create this file, run this command:
.. code-block:: console
# apt-get install keystone
The Identity service is installed with MySQL as the database back end,
``keystonedb`` as database name, and the localhost socket file. The
corresponding DSN (Database Source Name) will then be:
.. code-block:: ini
[database]
connection = mysql+pymysql://keystone:PASSWORD@localhost/keystonedb
The ``dbconfig-common`` package will configure MySQL for these access
rights, and create the database for you. Since OpenStack 2014.1.1, all
OpenStack packages in Debian are performing the following MySQL query
after database creation (if you decide to use MySQL as a back-end):
.. code-block:: ini
ALTER DATABASE keystone CHARACTER SET utf8 COLLATE utf8_unicode_ci
So, if using Debian, you wont need to care about database creation,
access rights and character sets. All that is handled for you by the
packages.
As an example, here are screenshots from the ``cinder-common`` package:
.. image:: ../figures/debconf-screenshots/dbconfig-common_1_configure-with-dbconfig-yes-no.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_2_db-types.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_3_connection_method.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_4_mysql_root_password.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_5_mysql_app_password.png
|
.. image:: ../figures/debconf-screenshots/dbconfig-common_6_mysql_app_password_confirm.png
|
By default in Debian, you can access the MySQL server from either
localhost through the socket file or 127.0.0.1. To access it over the
network, you must edit the :file:`/etc/mysql/my.cnf` file, and the
``mysql.user`` table. To do so, Debian provides a helper script in the
``openstack-deploy`` package. To use it, install the package:
.. code-block:: console
# apt-get install openstack-deploy
and run the helper script:
.. code-block:: console
# /usr/share/openstack-deploy/mysql-remote-root
Alternatively, if you do not want to install this package, run this
script to enable remote root access:
.. code-block:: bash
#!/bin/sh
set -e
SQL="mysql --defaults-file=/etc/mysql/debian.cnf -Dmysql -e"
ROOT_PASS=`${SQL} "SELECT Password FROM user WHERE User='root' LIMIT 1;" \
| tail -n 1`
${SQL} "REPLACE INTO user SET host='%', user='root',\
password='${ROOT_PASS}', Select_priv='Y', Insert_priv='Y',\
Update_priv='Y', Delete_priv='Y', Create_priv='Y', Drop_priv='Y',\
Reload_priv='Y', Shutdown_priv='Y', Process_priv='Y', File_priv='Y',\
Grant_priv='Y', References_priv='Y', Index_priv='Y', Alter_priv='Y',\
Super_priv='Y', Show_db_priv='Y', Create_tmp_table_priv='Y',\
Lock_tables_priv='Y', Execute_priv='Y', Repl_slave_priv='Y',\
Repl_client_priv='Y', Create_view_priv='Y', Show_view_priv='Y',\
Create_routine_priv='Y', Alter_routine_priv='Y', Create_user_priv='Y',\
Event_priv='Y', Trigger_priv='Y' "
${SQL} "FLUSH PRIVILEGES"
sed -i 's|^bind-address[ \t]*=.*|bind-address = 0.0.0.0|' /etc/mysql/my.cnf
/etc/init.d/mysql restart
You must enable remote access before you install OpenStack services on
multiple nodes.

56
doc/install-guide/source/debconf/debconf-keystone-authtoken.rst
View File

@ -1,56 +0,0 @@
:orphan:
======================================
Services and the [keystone_authtoken]
======================================
Because most OpenStack services must access the Identity service, you
must configure the IP address of the ``keystone`` server to be able to
access it. You must also configure the ``admin_tenant_name``,
``admin_user``, and ``admin_password`` options for each service to work.
Generally, this section looks like this:
.. code-block:: ini
[keystone_authtoken]
auth_uri = http://controller:5000/v2.0
identity_uri = http://controller:35357
admin_tenant_name = %SERVICE_TENANT_NAME%
admin_user = %SERVICE_USER%
admin_password = %SERVICE_PASSWORD%
The debconf system helps users configure the ``auth_uri``,
``identity_uri``, ``admin_tenant_name``, ``admin_user``, and
``admin_password`` options.
The following screens show an example Image service configuration:
.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_server_hostname.png
|
.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_tenant_name.png
|
.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_tenant_admin_user.png
|
.. image:: ../figures/debconf-screenshots/service_keystone_authtoken_admin_password.png
This information is stored in the configuration file for each service.
For example:
.. code-block:: ini
/etc/ceilometer/ceilometer.conf
/etc/nova/api-paste.ini
/etc/glance/glance-api-paste.ini
/etc/glance/glance-registry.ini
/etc/cinder/cinder.conf
/etc/neutron/neutron.conf
The Debian OpenStack packages offer automation for this, so OpenStack
users do not have to manually edit the configuration files.

36
doc/install-guide/source/debconf/debconf-rabbitmq.rst
View File

@ -1,36 +0,0 @@
:orphan:
===============================
RabbitMQ credentials parameters
===============================
For every package that must connect to a Messaging Server, the Debian
package enables you to configure the IP address for that server and the
user name and password that is used to connect. The following example
shows configuration with the ``ceilometer-common`` package:
.. image:: ../figures/debconf-screenshots/rabbitmq-host.png
|
.. image:: ../figures/debconf-screenshots/rabbitmq-user.png
|
.. image:: ../figures/debconf-screenshots/rabbitmq-password.png
|
These debconf screens appear in: ``ceilometer-common``, ``cinder-common``,
``glance-common``, ``heat-common``, ``neutron-common``, and ``nova-common``.
This will configure the below directives (example from ``nova.conf``):
.. code-block:: ini
[DEFAULT]
rabbit_host=localhost
rabbit_userid=guest
rabbit_password=guest
The other directives concerning RabbitMQ will stay untouched.

14
doc/install-guide/source/debconf/debconf.rst
View File

@ -1,14 +0,0 @@
:orphan:
================================
Configure OpenStack with debconf
================================
.. toctree::
:maxdepth: 2
debconf-concepts.rst
debconf-dbconfig-common.rst
debconf-rabbitmq.rst
debconf-keystone-authtoken.rst
debconf-api-endpoints.rst

5
doc/install-guide/source/glance-install.rst
View File

@ -295,8 +295,9 @@ Install and configure components
# apt-get install glance python-glanceclient # apt-get install glance python-glanceclient
#. Respond to prompts for #. Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`,
.. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

5
doc/install-guide/source/heat-install.rst
View File

@ -454,8 +454,9 @@ Install and configure components
# apt-get install heat-api heat-api-cfn heat-engine python-heat-client # apt-get install heat-api heat-api-cfn heat-engine python-heat-client
#. Respond to prompts for #. Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`,
.. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

63
doc/install-guide/source/index.rst
View File

@ -75,54 +75,33 @@ This guide documents OpenStack Newton release.
Contents Contents
~~~~~~~~ ~~~~~~~~
.. toctree::
:maxdepth: 2
common/conventions.rst
overview.rst
environment.rst
keystone.rst
glance.rst
nova.rst
neutron.rst
horizon.rst
cinder.rst
manila.rst
swift.rst
heat.rst
ceilometer.rst
trove.rst
launch-instance.rst
.. Pseudo only directive for each distribution used by the build tool. .. Pseudo only directive for each distribution used by the build tool.
This pseudo only directive for toctree only works fine with Tox. This pseudo only directive for toctree only works fine with Tox.
When you directly build this guide with Sphinx, When you directly build this guide with Sphinx,
some navigation menu may not work properly. some navigation menu may not work properly.
.. Keep this pseudo only directive not to break translation tool chain
at the openstack-doc-tools repo until it is changed.
.. only:: obs or rdo or ubuntu .. only:: obs or rdo or ubuntu
.. toctree::
:maxdepth: 2
common/conventions.rst
overview.rst
environment.rst
keystone.rst
glance.rst
nova.rst
neutron.rst
horizon.rst
cinder.rst
manila.rst
swift.rst
heat.rst
ceilometer.rst
trove.rst
launch-instance.rst
.. only:: debian .. 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
manila.rst
swift.rst
heat.rst
ceilometer.rst
trove.rst
launch-instance.rst
.. end of contents .. end of contents
Appendix Appendix

5
doc/install-guide/source/keystone-install.rst
View File

@ -162,7 +162,10 @@ HTTP server to handle requests.
# apt-get install keystone # apt-get install keystone
#. Respond to prompts for :doc:`debconf/debconf-dbconfig-common`, #. Respond to prompts for debconf,
which will fill the below database access directive.
.. :doc:`debconf/debconf-dbconfig-common`,
which will fill the below database access directive. which will fill the below database access directive.
.. code-block:: ini .. code-block:: ini

5
doc/install-guide/source/manila-controller-install.rst
View File

@ -247,8 +247,9 @@ Install and configure components
.. only:: debian .. only:: debian
Respond to prompts for Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`,
.. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

5
doc/install-guide/source/nova-compute-install.rst
View File

@ -52,8 +52,9 @@ Install and configure components
.. only:: debian .. only:: debian
Respond to prompts for Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`,
.. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. Make and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. Make
sure that you do not activate database management handling by debconf, sure that you do not activate database management handling by debconf,

5
doc/install-guide/source/nova-controller-install.rst
View File

@ -192,8 +192,9 @@ Install and configure components
# apt-get install nova-api nova-conductor nova-consoleauth \ # apt-get install nova-api nova-conductor nova-consoleauth \
nova-consoleproxy nova-scheduler python-novaclient nova-consoleproxy nova-scheduler python-novaclient
Respond to prompts for Respond to prompts for debconf.
:doc:`database management <debconf/debconf-dbconfig-common>`,
.. :doc:`database management <debconf/debconf-dbconfig-common>`,
:doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`, :doc:`Identity service credentials <debconf/debconf-keystone-authtoken>`,
:doc:`service endpoint registration <debconf/debconf-api-endpoints>`, :doc:`service endpoint registration <debconf/debconf-api-endpoints>`,
and :doc:`message broker credentials <debconf/debconf-rabbitmq>`. and :doc:`message broker credentials <debconf/debconf-rabbitmq>`.

40
tools/build-install-guides-rst.sh
View File

@ -16,7 +16,7 @@ fi
# because our tools generate translation resources from # because our tools generate translation resources from
# only one index file. # only one index file.
# Therefore, this tool uses one combined index file # Therefore, this tool uses one combined index file
# while processing title and toctree for each distribution. # while processing title for each distribution.
# Save and restore the index file # Save and restore the index file
cp -f ${INDEX} ${INDEX}.save cp -f ${INDEX} ${INDEX}.save
@ -27,8 +27,7 @@ for tag in $TAGS; do
# Build the guide with debconf # Build the guide with debconf
# To use debian only contents, use "debian" tag. # To use debian only contents, use "debian" tag.
tools/build-rst.sh doc/install-guide-debconf \ tools/build-rst.sh doc/install-guide-debconf \
$GLOSSARY --tag debian --target "draft/install-guide-debconf" \ --tag debian --target "draft/install-guide-${tag}" $LINKCHECK
$LINKCHECK
else else
## ##
# Because Sphinx uses the first heading as title regardless of # Because Sphinx uses the first heading as title regardless of
@ -39,43 +38,8 @@ for tag in $TAGS; do
sed -n 4p | sed -e 's/^ *//g') sed -n 4p | sed -e 's/^ *//g')
sed -i -e "s/\.\. title::.*/.. title:: ${title}/" ${INDEX} 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 # Build the guide
tools/build-rst.sh doc/install-guide \ tools/build-rst.sh doc/install-guide \
--tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK --tag ${tag} --target "draft/install-guide-${tag}" $LINKCHECK
# 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
fi
fi fi
done done