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 <last-part-of-url.html>`

And for the deploy guide:

    :deploy_guide:`Link title text <last-part-of-url.html>`

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

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
+<extending.html#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
 ~~~~~~~~~~~~~~~~~~~~~~

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 <http://docs.openstack.org/developer/openstack-ansible/install-guide/app-advanced-config-affinity.html>`_
+- Adjust the :deploy_guide:`affinity <app-advanced-config-affinity.html>`
   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.

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

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

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 <http://docs.openstack.org/project-deploy-guide/openstack-ansible/newton/app-custom-layouts.html>`_
+     found in :deploy_guide:`Appendix C <app-custom-layouts.html>`
      of the Deployment Guide.
 
    * Load balancer configuration