From 5a8e199ca1ac525c1f6a5a5c3d61964f2393dfce Mon Sep 17 00:00:00 2001 From: Jean-Philippe Evrard Date: Fri, 23 Mar 2018 17:39:27 +0000 Subject: [PATCH] [Docs] Simplify docs configuration We don't need that many variables for the deployment guide, there is barely any substitutions done. Simplify the documentation to a bare minimum. On top of this, we adapt for the latest openstackdocstheme. Change-Id: I3502b6a943bacc6dac1b757961348eb04771750d --- deploy-guide/source/conf.py | 119 ++++++++++++++---------------------- 1 file changed, 47 insertions(+), 72 deletions(-) diff --git a/deploy-guide/source/conf.py b/deploy-guide/source/conf.py index 4331b496c6..1b5ca68d1e 100644 --- a/deploy-guide/source/conf.py +++ b/deploy-guide/source/conf.py @@ -23,14 +23,58 @@ # serve to show the default. import os -import pbr.version import sys +import openstackdocstheme + +# -- OpenStack-Ansible configuration -------------------------------------- +# Variables to override +target_name = 'openstack-ansible' +description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.' +previous_series_name = 'queens' +current_series_name = 'rocky' + +# General information about the project. +author = 'OpenStack-Ansible Contributors' +category = 'Miscellaneous' +copyright = '2014-2018, OpenStack-Ansible Contributors' +title = 'OpenStack-Ansible Documentation' + +# Smart variable replacements with what we can. The openstackdocstheme has +# no stable interface though. This works with 1.20. +current_series = openstackdocstheme.ext._get_series_name() + +if current_series == "latest": + watermark = "Pre-release" + latest_tag = "master" +else: + watermark = series_names = current_series.capitalize() + latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n') + +deploy_guide_prefix = "http://docs.openstack.org/project-deploy-guide/openstack-ansible/{}/%s".format(current_series) +dev_docs_prefix = "http://docs.openstack.org/openstack-ansible/{}/%s".format(current_series) +role_docs_prefix = "http://docs.openstack.org/openstack-ansible-%s/{}".format(current_series) + + +# Substitutions loader +rst_epilog = """ +.. |latest_tag| replace:: {latest_tag} +""".format( + latest_tag=latest_tag, +) + +# Format: Reference name: (string containing %s for substitution, linkname) +extlinks = {'deploy_guide': (deploy_guide_prefix, ''), + 'dev_docs': (dev_docs_prefix, ''), + 'role_docs': (role_docs_prefix, '') +} + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../../inventory/')) + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -59,29 +103,9 @@ source_suffix = '.rst' # The master toctree document. master_doc = 'index' -# General information about the project. -author = 'OpenStack-Ansible Contributors' -category = 'Miscellaneous' -copyright = '2014-2016, OpenStack-Ansible Contributors' -description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.' -project = 'OpenStack-Ansible' -target_name = 'openstack-ansible' -title = 'OpenStack-Ansible Deployment Guide' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version_info = pbr.version.VersionInfo(target_name) -# The full version, including alpha/beta/rc tags. -release = version_info.version_string_with_vcs() -# The short X.Y version. -version = version_info.canonical_version_string() - # openstackdocstheme options repository_name = 'openstack/' + target_name -bug_project = project.lower() +bug_project = 'openstack-ansible' bug_tag = '' # The language for content autogenerated by Sphinx. Refer to documentation @@ -271,7 +295,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ (master_doc, target_name, - title, author, project, + title, author, bug_project, description, category), ] @@ -294,55 +318,6 @@ pdf_documents = [ title, author) ] -latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n') - -previous_release_branch_name='queens' -current_release_branch_name='rocky' -# 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+"``" - -rst_epilog = """ -.. |previous_release_branch_name| replace:: %s -.. |current_release_branch_name| replace:: %s -.. |previous_release_capital_name| replace:: %s -.. |previous_release_formal_name| replace:: %s -.. |current_release_capital_name| replace:: %s -.. |current_release_formal_name| replace:: %s -.. |upgrade_backup_dir| replace:: %s -.. |latest_tag| replace:: %s -""" % (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) - -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" - deploy_branch_link_name = "latest" - 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/openstack-ansible/{}/%s".format(deploy_branch_link_name) -role_docs_prefix = "http://docs.openstack.org/openstack-ansible-%s/{}".format(dev_branch_link_name) - -extlinks = {'deploy_guide': (deploy_guide_prefix, ''), - 'dev_docs': (dev_docs_prefix, ''), - 'role_docs': (role_docs_prefix, '') -} - # -- Options for sphinxmark ----------------------------------------------- sphinxmark_enable = True sphinxmark_div = 'docs-body'