[docs] Resolve errors and simplify sphinx config

This patch does the following: - Simplifies the sphinx configuration introduced in https://review.openstack.org/371722 to reduce the number of variables involved. The variables are also ordered in the same way everywhere to make it easier to read and troubleshoot. - Simplifies some of the CLI guides to be more explicit about the tag to checkout when cloning the git repo. - Cleaned up some references which went to non-existant documents. - Added a link to the networking appendix. - As per https://review.openstack.org/369650 the backup directory for the upgrade process is now the name of the source version the upgrade process is working with. Change-Id: Iee30a32f99a66d9facb049311cadf1b9a8b2170e
2016-09-19 12:08:53 +01:00 · 2016-09-19 12:08:53 +01:00 · 10a7d80b79
commit 10a7d80b79
parent 39280be7dd
14 changed files with 37 additions and 47 deletions
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@ -300,29 +300,31 @@ pdf_documents = [
     title, author)
 ]

-pipe = Popen('git describe --abbrev=0 --tags', stdout=PIPE, shell=True)
+latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n')

 previous_release_branch_name='mitaka'
 current_release_branch_name='newton'
-version = pipe.stdout.read()

 previous_release_capital_name=previous_release_branch_name.upper()
 previous_release_formal_name=previous_release_branch_name.capitalize()
-current_release_formal_name=current_release_branch_name.capitalize()
 current_release_capital_name=current_release_branch_name.upper()
-current_release_deploy_dir="``/etc/openstack_deploy."+current_release_capital_name+"``"
-upgrade_deploy_vars_file="``/etc/openstack_deploy."+current_release_capital_name+"/VARS_MIGRATED_file``"
-upgrade_deploy_vars_user="``/etc/openstack_deploy."+current_release_capital_name+"/VARS_MIGRATED_user_variables``"
+current_release_formal_name=current_release_branch_name.capitalize()
+upgrade_backup_dir="``/etc/openstack_deploy."+previous_release_capital_name+"``"

 rst_epilog = """
-.. |current_release_branch_name| replace:: %s
 .. |previous_release_branch_name| replace:: %s
+.. |current_release_branch_name| replace:: %s
 .. |previous_release_capital_name| replace:: %s
-.. |current_release_capital_name| replace:: %s
 .. |previous_release_formal_name| replace:: %s
+.. |current_release_capital_name| replace:: %s
 .. |current_release_formal_name| replace:: %s
-.. |current_release_deploy_dir| replace:: %s
-.. |upgrade_deploy_vars_file| replace:: %s
-.. |upgrade_deploy_vars_user| replace:: %s
+.. |upgrade_backup_dir| replace:: %s
 .. |latest_tag| replace:: %s
-""" % (current_release_branch_name,previous_release_branch_name,previous_release_capital_name,current_release_capital_name,previous_release_formal_name,current_release_formal_name,current_release_deploy_dir,upgrade_deploy_vars_file,upgrade_deploy_vars_user,version)
+""" % (previous_release_branch_name,
+       current_release_branch_name,
+       previous_release_capital_name,
+       previous_release_formal_name,
+       current_release_capital_name,
+       current_release_formal_name,
+       upgrade_backup_dir,
+       latest_tag)
--- a/doc/source/developer-docs/ops.rst
+++ b/doc/source/developer-docs/ops.rst
@ -11,7 +11,6 @@ installed environments.
   ops-add-computehost.rst
   ops-remove-computehost.rst
   ops-galera.rst
-   ops-logging.rst
   ops-tips.rst
   ops-troubleshooting.rst

--- a/doc/source/install-guide/app-advanced-config-options.rst
+++ b/doc/source/install-guide/app-advanced-config-options.rst
@ -1,5 +1,5 @@
 ===================================
-Appendix E: Advanced configuration
+Appendix F: Advanced configuration
 ===================================

 .. toctree::
--- a/doc/source/install-guide/app-networking.rst
+++ b/doc/source/install-guide/app-networking.rst
@ -1,7 +1,7 @@
 .. _network-appendix:

 ================================
-Appendix F: Container networking
+Appendix E: Container networking
 ================================

 OpenStack-Ansible deploys LXC machine containers and uses linux bridging
--- a/doc/source/install-guide/app-resources.rst
+++ b/doc/source/install-guide/app-resources.rst
@ -1,5 +1,5 @@
 =================================
-Appendix F: Additional resources
+Appendix G: Additional resources
 =================================

 The following Ansible resources are useful to reference:
--- a/doc/source/install-guide/app.rst
+++ b/doc/source/install-guide/app.rst
@ -9,5 +9,6 @@ Appendices
   app-config-prod.rst
   app-custom-layouts.rst
   app-security.rst
+   app-networking.rst
   app-advanced-config-options.rst
   app-resources.rst
--- a/doc/source/install-guide/configure.rst
+++ b/doc/source/install-guide/configure.rst
@ -4,11 +4,6 @@
 Configure deployment
 ====================

-.. toctree::
-   :maxdepth: 2
-
-   configure-user-config-examples.rst
-
 .. figure:: figures/installation-workflow-configure-deployment.png
   :width: 100%

--- a/doc/source/install-guide/deploymenthost.rst
+++ b/doc/source/install-guide/deploymenthost.rst
@ -61,14 +61,12 @@ Installing source and dependencies

 Install the source and dependencies for the deployment host.

-#. Clone the OSA repository into the ``/opt/openstack-ansible``
-   directory:
+#. Clone the latest stable release of the OpenStack-Ansible git repository into
+   the ``/opt/openstack-ansible`` directory:

-   .. code-block:: shell-session
+   .. parsed-literal::

-       # git clone -b TAG https://github.com/openstack/openstack-ansible.git /opt/openstack-ansible
-
-   Replace ``TAG`` with the current stable release tag : |my_conf_val|
+       # git clone -b |latest_tag| https://github.com/openstack/openstack-ansible /opt/openstack-ansible

 #. Change to the ``/opt/openstack-ansible`` directory, and run the
   Ansible bootstrap script:
--- a/doc/source/upgrade-guide/manual-upgrade.rst
+++ b/doc/source/upgrade-guide/manual-upgrade.rst
@ -16,13 +16,11 @@ Check out the |current_release_formal_name| release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Ensure your OpenStack-Ansible code is on the latest
-|current_release_formal_name| release tag (|latest_tag|).
+|current_release_formal_name| tagged release.

 .. parsed-literal::

-    # git checkout stable/|current_release_branch_name|
-    # LATEST_TAG=$(git describe --abbrev=0 --tags)
-    # git checkout ${LATEST_TAG}
+    # git checkout |latest_tag|

 Prepare the shell variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- a/doc/source/upgrade-guide/minor-upgrade.rst
+++ b/doc/source/upgrade-guide/minor-upgrade.rst
@ -18,13 +18,11 @@ A minor upgrade typically requires the following steps:
      # cd /opt/openstack-ansible

 #. Ensure your OpenStack-Ansible code is on the latest
-   |current_release_formal_name| release tag (|latest_tag|):
+   |current_release_formal_name| tagged release:

   .. parsed-literal::

-      # git checkout stable/|current_release_branch_name|
-      # LATEST_TAG=$(git describe --abbrev=0 --tags)
-      # git checkout ${LATEST_TAG}
+      # git checkout |latest_tag|

 #. Update all the dependent roles to the latest version:

--- a/doc/source/upgrade-guide/overview.rst
+++ b/doc/source/upgrade-guide/overview.rst
@ -19,8 +19,8 @@ major upgrade process performs the following actions:
 - Modifies files residing in ``/etc/openstack_deploy`` in
  order to reflect new configuration values.
 - Some flag files are created by the migration scripts in order to achieve
-  idempotency. These files are placed in the |current_release_deploy_dir|
-  directory.
+  idempotency. These files are placed in the
+  |upgrade_backup_dir| directory.
 - Upgrade the RabbitMQ server during an OpenStack-Ansible upgrade process.
  See :ref:`setup-infra-playbook` for details.

--- a/doc/source/upgrade-guide/reference-scripts.rst
+++ b/doc/source/upgrade-guide/reference-scripts.rst
@ -35,11 +35,12 @@ strings in the variable override files matching the pattern
 ``/etc/openstack_deploy/user_*.yml``.
 Variable names within comments are updated.

-This script creates files of the form
-|upgrade_deploy_vars_file|. For example, once the
-script has processed the file ``/etc/openstack_deploy/user_variables.yml``, it
-creates |upgrade_deploy_vars_user|. This
-indicates to OpenStack-Ansible to skip this step on successive runs. The script
-itself does not check for this file.
+This script creates files of the form ``VARS_MIGRATED_<filename>`` and
+places them in |upgrade_backup_dir|.
+For example, once the script has processed the file
+``/etc/openstack_deploy/user_variables.yml``, it creates
+``VARS_MIGRATED_user_variables.yml`` in |upgrade_backup_dir|.
+This indicates to OpenStack-Ansible to skip this step on successive runs. The
+script itself does not check for this file.

 Called by :ref:`config-change-playbook`
--- a/doc/source/upgrade-guide/reference-upgrade-playbooks.rst
+++ b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst
@ -40,7 +40,7 @@ This playbook backs up the ``/etc/openstack_deploy`` directory before
 changing the configuration.

 ``/etc/openstack_deploy`` copies once to
-|current_release_deploy_dir|.
+|upgrade_backup_dir|.

 .. _user-secrets-playbook:

--- a/doc/source/upgrade-guide/script-upgrade.rst
+++ b/doc/source/upgrade-guide/script-upgrade.rst
@ -23,8 +23,6 @@ directoy:

 .. parsed-literal::

-   # git checkout stable/|current_release_branch_name|
-   # LATEST_TAG=$(git describe --abbrev=0 --tags)
-   # git checkout ${LATEST_TAG}
+   # git checkout |latest_tag|
   # ./scripts/run-upgrade.sh