[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

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)

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
 

doc/source/install-guide/app-advanced-config-options.rst

@@ -1,5 +1,5 @@
 ===================================
-Appendix E: Advanced configuration
+Appendix F: Advanced configuration
 ===================================
 
 .. toctree::

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

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:

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

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%
 

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:

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:
 

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.
 

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`

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:
 

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