From a1a25002ba02c9fdeb32623470dfd914ef069d30 Mon Sep 17 00:00:00 2001 From: Nolan Brubaker Date: Mon, 9 Jan 2017 12:04:58 -0500 Subject: [PATCH] Add conditional branch names for docs links Since the deploy guide moved to a separate directory structure, relative links throughout the docs have been pointing to nothing. This change applies some logic to figure out the correct format for URLs based on the current branch and the deploy guide/dev docs conventions. The actual link generation is done via the sphinx.ext.extlinks extension, which allows for defining custom link generation roles. This achieves the desired behavior in terms of dynamic link construction, but does alter the standard linking conventions. Another side effect is that docs generate this way will always point to the live URLs, not to HTML generated for a gate job. It may be worthwhile using relative links within the deploy guide/developer docs and only using these automatic external ones for cross-references. Usage for dev docs looks like this: :dev_docs:`Link title text ` And for the deploy guide: :deploy_guide:`Link title text ` Some examples inline have been provided, to demonstrate how these fit in different contexts. Some small code style fixes are also included. Change-Id: I4d065f1f2d7c1372f3f829ab9e5297d5028f2ee6 --- .../source/app-advanced-config-override.rst | 6 ++-- deploy-guide/source/app-custom-layouts.rst | 3 +- deploy-guide/source/conf.py | 28 ++++++++++++++----- doc/source/conf.py | 28 ++++++++++++++----- .../developer-docs/additional-roles.rst | 2 +- 5 files changed, 47 insertions(+), 20 deletions(-) diff --git a/deploy-guide/source/app-advanced-config-override.rst b/deploy-guide/source/app-advanced-config-override.rst index c253d36b68..f7610f7520 100644 --- a/deploy-guide/source/app-advanced-config-override.rst +++ b/deploy-guide/source/app-advanced-config-override.rst @@ -17,11 +17,11 @@ configuration entries in the ``/etc/openstack_deploy/user_variables.yml``. This section describes how to use the configuration entries in the ``/etc/openstack_deploy/user_variables.yml`` file to override default configuration settings. For more information, see the -`Setting overrides in configuration files`_ section in the developer -documentation. +:dev_docs:`Setting overrides in configuration files +` section in the +developer documentation. .. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/ -.. _Setting overrides in configuration files: ../developer-docs/extending.html#setting-overrides-in-configuration-files Overriding .conf files ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/deploy-guide/source/app-custom-layouts.rst b/deploy-guide/source/app-custom-layouts.rst index f9fb04cec4..5cb4ba4e92 100644 --- a/deploy-guide/source/app-custom-layouts.rst +++ b/deploy-guide/source/app-custom-layouts.rst @@ -122,8 +122,7 @@ To omit a component from a deployment, you can use one of several options: - Do not run the playbook that installs the component. Unless you specify the component to run directly on a host by using the ``is_metal`` property, a container is created for this component. -- Adjust the - `affinity `_ +- Adjust the :deploy_guide:`affinity ` to 0 for the host group. Similar to the second option listed here, Unless you specify the component to run directly on a host by using the``is_metal`` property, a container is created for this component. diff --git a/deploy-guide/source/conf.py b/deploy-guide/source/conf.py index eebc36c5d9..03822a3ddd 100644 --- a/deploy-guide/source/conf.py +++ b/deploy-guide/source/conf.py @@ -41,7 +41,7 @@ sys.path.insert(0, os.path.abspath('../../playbooks/inventory/')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. # TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' -extensions = ['sphinx.ext.autodoc','sphinxmark'] +extensions = ['sphinx.ext.autodoc','sphinxmark', 'sphinx.ext.extlinks'] # Add any paths that contain templates here, relative to this directory. #templates_path = ['_templates'] @@ -303,12 +303,17 @@ latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n') previous_release_branch_name='newton' current_release_branch_name='ocata' +# Var specifically for using in URLs; differs because it might be 'draft' +# on master for deploy guide +deploy_branch_link_name = current_release_branch_name +# dev docs have no branch specified on master; for stable braches it's "/branch/" +dev_branch_link_name = "{}/".format(current_release_branch_name) -previous_release_capital_name=previous_release_branch_name.upper() -previous_release_formal_name=previous_release_branch_name.capitalize() -current_release_capital_name=current_release_branch_name.upper() -current_release_formal_name=current_release_branch_name.capitalize() -upgrade_backup_dir="``/etc/openstack_deploy."+previous_release_capital_name+"``" +previous_release_capital_name = previous_release_branch_name.upper() +previous_release_formal_name = previous_release_branch_name.capitalize() +current_release_capital_name = current_release_branch_name.upper() +current_release_formal_name = current_release_branch_name.capitalize() +upgrade_backup_dir = "``/etc/openstack_deploy."+previous_release_capital_name+"``" rst_epilog = """ .. |previous_release_branch_name| replace:: %s @@ -330,7 +335,16 @@ rst_epilog = """ watermark = os.popen("git branch --contains $(git rev-parse HEAD) | awk -F/ '/stable/ {print $2}'").read().strip(' \n\t').capitalize() if watermark == "": - watermark = "Pre-release" + watermark = "Pre-release" + deploy_branch_link_name = "draft" + dev_branch_link_name = "" + +deploy_guide_prefix = "http://docs.openstack.org/project-deploy-guide/openstack-ansible/{}/%s".format(deploy_branch_link_name) +dev_docs_prefix = "http://docs.openstack.org/developer/openstack-ansible/developer-docs/{}%s".format(dev_branch_link_name) + +extlinks = {'deploy_guide': (deploy_guide_prefix, ''), + 'dev_docs': (dev_docs_prefix, '') +} # -- Options for sphinxmark ----------------------------------------------- sphinxmark_enable = True diff --git a/doc/source/conf.py b/doc/source/conf.py index d6e7b671be..24296a28e6 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -41,7 +41,7 @@ sys.path.insert(0, os.path.abspath('../../playbooks/inventory/')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. # TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' -extensions = ['sphinx.ext.autodoc','sphinxmark'] +extensions = ['sphinx.ext.autodoc','sphinxmark', 'sphinx.ext.extlinks'] # Add any paths that contain templates here, relative to this directory. #templates_path = ['_templates'] @@ -303,12 +303,17 @@ latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n') previous_release_branch_name='newton' current_release_branch_name='ocata' +# Var specifically for using in URLs; differs because it might be 'draft' +# on master for deploy guide +deploy_branch_link_name = current_release_branch_name +# dev docs have no branch specified on master; for stable braches it's "/branch/" +dev_branch_link_name = "{}/".format(current_release_branch_name) -previous_release_capital_name=previous_release_branch_name.upper() -previous_release_formal_name=previous_release_branch_name.capitalize() -current_release_capital_name=current_release_branch_name.upper() -current_release_formal_name=current_release_branch_name.capitalize() -upgrade_backup_dir="``/etc/openstack_deploy."+previous_release_capital_name+"``" +previous_release_capital_name = previous_release_branch_name.upper() +previous_release_formal_name = previous_release_branch_name.capitalize() +current_release_capital_name = current_release_branch_name.upper() +current_release_formal_name = current_release_branch_name.capitalize() +upgrade_backup_dir = "``/etc/openstack_deploy."+previous_release_capital_name+"``" rst_epilog = """ .. |previous_release_branch_name| replace:: %s @@ -330,7 +335,16 @@ rst_epilog = """ watermark = os.popen("git branch --contains $(git rev-parse HEAD) | awk -F/ '/stable/ {print $2}'").read().strip(' \n\t').capitalize() if watermark == "": - watermark = "Pre-release" + watermark = "Pre-release" + deploy_branch_link_name = "draft" + dev_branch_link_name = "" + +deploy_guide_prefix = "http://docs.openstack.org/project-deploy-guide/openstack-ansible/{}/%s".format(deploy_branch_link_name) +dev_docs_prefix = "http://docs.openstack.org/developer/openstack-ansible/developer-docs/{}%s".format(dev_branch_link_name) + +extlinks = {'deploy_guide': (deploy_guide_prefix, ''), + 'dev_docs': (dev_docs_prefix, '') +} # -- Options for sphinxmark ----------------------------------------------- sphinxmark_enable = True diff --git a/doc/source/developer-docs/additional-roles.rst b/doc/source/developer-docs/additional-roles.rst index da08b863bc..6a6f292a1d 100644 --- a/doc/source/developer-docs/additional-roles.rst +++ b/doc/source/developer-docs/additional-roles.rst @@ -261,7 +261,7 @@ The development of a role will usually go through the following stages: This is implemented into the dynamic inventory through the definition of content in an ``env.d`` file. A description of how these work can be - found in `Appendix C `_ + found in :deploy_guide:`Appendix C ` of the Deployment Guide. * Load balancer configuration