From 10a7d80b790fce07e27bb3fe8e2d708dcedadad3 Mon Sep 17 00:00:00 2001 From: Jesse Pretorius Date: Mon, 19 Sep 2016 12:08:53 +0100 Subject: [PATCH] [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 | 26 ++++++++++--------- doc/source/developer-docs/ops.rst | 1 - .../app-advanced-config-options.rst | 2 +- doc/source/install-guide/app-networking.rst | 2 +- doc/source/install-guide/app-resources.rst | 2 +- doc/source/install-guide/app.rst | 1 + doc/source/install-guide/configure.rst | 5 ---- doc/source/install-guide/deploymenthost.rst | 10 +++---- doc/source/upgrade-guide/manual-upgrade.rst | 6 ++--- doc/source/upgrade-guide/minor-upgrade.rst | 6 ++--- doc/source/upgrade-guide/overview.rst | 4 +-- .../upgrade-guide/reference-scripts.rst | 13 +++++----- .../reference-upgrade-playbooks.rst | 2 +- doc/source/upgrade-guide/script-upgrade.rst | 4 +-- 14 files changed, 37 insertions(+), 47 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 16925e22d4..aa7011ae24 100644 --- 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) diff --git a/doc/source/developer-docs/ops.rst b/doc/source/developer-docs/ops.rst index 0a8d7872db..941e5d83d0 100644 --- 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 diff --git a/doc/source/install-guide/app-advanced-config-options.rst b/doc/source/install-guide/app-advanced-config-options.rst index 8730ca8ff6..19c4bb5f61 100644 --- 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:: diff --git a/doc/source/install-guide/app-networking.rst b/doc/source/install-guide/app-networking.rst index 443f1dbfe3..190f79c739 100644 --- 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 diff --git a/doc/source/install-guide/app-resources.rst b/doc/source/install-guide/app-resources.rst index 295f3f6db9..e60fe506f1 100644 --- 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: diff --git a/doc/source/install-guide/app.rst b/doc/source/install-guide/app.rst index 2fc3d8a807..2eb069078a 100644 --- 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 diff --git a/doc/source/install-guide/configure.rst b/doc/source/install-guide/configure.rst index 6b6b892ce9..cf9b55cba3 100644 --- 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% diff --git a/doc/source/install-guide/deploymenthost.rst b/doc/source/install-guide/deploymenthost.rst index 24fc4a3d0c..0c61cdd96e 100644 --- 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: diff --git a/doc/source/upgrade-guide/manual-upgrade.rst b/doc/source/upgrade-guide/manual-upgrade.rst index d7d487fff2..5483c92e3f 100644 --- 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/upgrade-guide/minor-upgrade.rst b/doc/source/upgrade-guide/minor-upgrade.rst index 222015f181..ab834f5c1a 100644 --- 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: diff --git a/doc/source/upgrade-guide/overview.rst b/doc/source/upgrade-guide/overview.rst index 2d8ca9be21..b9c0655923 100644 --- 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. diff --git a/doc/source/upgrade-guide/reference-scripts.rst b/doc/source/upgrade-guide/reference-scripts.rst index 16e869c51e..359e650a92 100644 --- 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_`` 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` diff --git a/doc/source/upgrade-guide/reference-upgrade-playbooks.rst b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst index 13960dafa8..8984f9dd54 100644 --- 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: diff --git a/doc/source/upgrade-guide/script-upgrade.rst b/doc/source/upgrade-guide/script-upgrade.rst index db41671efa..4f7c826b9a 100644 --- 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