openstack/openstack-ansible
Code Issues Proposed changes

Add conditional branch names for docs links

Browse Source 
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
This commit is contained in:
Nolan Brubaker 2017-01-09 12:04:58 -05:00
parent e863f6b392
commit a1a25002ba
5 changed files with 47 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
deploy-guide/source/app-advanced-config-override.rst
View File

@ -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 This section describes how to use the configuration entries in the
``/etc/openstack_deploy/user_variables.yml`` file to override default ``/etc/openstack_deploy/user_variables.yml`` file to override default
configuration settings. For more information, see the configuration settings. For more information, see the
`Setting overrides in configuration files`_ section in the developer :dev_docs:`Setting overrides in configuration files
documentation. <extending.html#setting-overrides-in-configuration-files>` section in the
developer documentation.
.. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/ .. _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 Overriding .conf files
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~

3
deploy-guide/source/app-custom-layouts.rst
View File

@ -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. - Do not run the playbook that installs the component.
Unless you specify the component to run directly on a host by using the Unless you specify the component to run directly on a host by using the
``is_metal`` property, a container is created for this component. ``is_metal`` property, a container is created for this component.
- Adjust the - Adjust the :deploy_guide:`affinity <app-advanced-config-affinity.html>`
`affinity <http://docs.openstack.org/developer/openstack-ansible/install-guide/app-advanced-config-affinity.html>`_
to 0 for the host group. Similar to the second option listed here, Unless 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`` you specify the component to run directly on a host by using the``is_metal``
property, a container is created for this component. property, a container is created for this component.

28
deploy-guide/source/conf.py
View File

@ -41,7 +41,7 @@ sys.path.insert(0, os.path.abspath('../../playbooks/inventory/'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' # 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. # Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates'] #templates_path = ['_templates']
@ -303,12 +303,17 @@ latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n')
previous_release_branch_name='newton' previous_release_branch_name='newton'
current_release_branch_name='ocata' 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_capital_name = previous_release_branch_name.upper()
previous_release_formal_name=previous_release_branch_name.capitalize() previous_release_formal_name = previous_release_branch_name.capitalize()
current_release_capital_name=current_release_branch_name.upper() current_release_capital_name = current_release_branch_name.upper()
current_release_formal_name=current_release_branch_name.capitalize() current_release_formal_name = current_release_branch_name.capitalize()
upgrade_backup_dir="``/etc/openstack_deploy."+previous_release_capital_name+"``" upgrade_backup_dir = "``/etc/openstack_deploy."+previous_release_capital_name+"``"
rst_epilog = """ rst_epilog = """
.. |previous_release_branch_name| replace:: %s .. |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() watermark = os.popen("git branch --contains $(git rev-parse HEAD) | awk -F/ '/stable/ {print $2}'").read().strip(' \n\t').capitalize()
if watermark == "": 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 ----------------------------------------------- # -- Options for sphinxmark -----------------------------------------------
sphinxmark_enable = True sphinxmark_enable = True

28
doc/source/conf.py
View File

@ -41,7 +41,7 @@ sys.path.insert(0, os.path.abspath('../../playbooks/inventory/'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder' # 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. # Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates'] #templates_path = ['_templates']
@ -303,12 +303,17 @@ latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n')
previous_release_branch_name='newton' previous_release_branch_name='newton'
current_release_branch_name='ocata' 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_capital_name = previous_release_branch_name.upper()
previous_release_formal_name=previous_release_branch_name.capitalize() previous_release_formal_name = previous_release_branch_name.capitalize()
current_release_capital_name=current_release_branch_name.upper() current_release_capital_name = current_release_branch_name.upper()
current_release_formal_name=current_release_branch_name.capitalize() current_release_formal_name = current_release_branch_name.capitalize()
upgrade_backup_dir="``/etc/openstack_deploy."+previous_release_capital_name+"``" upgrade_backup_dir = "``/etc/openstack_deploy."+previous_release_capital_name+"``"
rst_epilog = """ rst_epilog = """
.. |previous_release_branch_name| replace:: %s .. |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() watermark = os.popen("git branch --contains $(git rev-parse HEAD) | awk -F/ '/stable/ {print $2}'").read().strip(' \n\t').capitalize()
if watermark == "": 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 ----------------------------------------------- # -- Options for sphinxmark -----------------------------------------------
sphinxmark_enable = True sphinxmark_enable = True

2
doc/source/developer-docs/additional-roles.rst
View File

@ -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 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 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. of the Deployment Guide.
* Load balancer configuration * Load balancer configuration