From 28b3b83cb202c132884345bc1be8314e22a9cc8e Mon Sep 17 00:00:00 2001
From: Adrian Andreias <adrian@fleio.com>
Date: Thu, 21 Oct 2021 20:40:44 +0300
Subject: [PATCH] docs: Parameterize kolla-ansible version and branch

Implement simple global variables system in docs and add global variables
KOLLA_OPENSTACK_RELEASE, KOLLA_ANSIBLE_MAJOR_VERSION  and
KOLLA_BRANCH_NAME.

Closes-Bug: #1844710
Change-Id: I2c131463eaf1c51eb8768f6d90e9697c77a7833b
Signed-off-by: Adrian Andreias <adrian@fleio.com>
---
 doc/source/conf.py             | 33 +++++++++++++++++++++++++++++++++
 doc/source/user/quickstart.rst | 12 ++++++++----
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8f1562ef01..620cb84a77 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -110,3 +110,36 @@ openstack_projects = [
     'swift',
     'watcher',
 ]
+
+# Global variables
+# For replacement, use in docs as |VAR_NAME| (note there's no space around variable name)
+# When adding new variables, make sure you add them to GLOBAL_VARIABLE_MAP dictionary as well
+
+KOLLA_ANSIBLE_MAJOR_VERSION = '9'
+
+# use 'master' or release name, e.g. 'victoria', 'xena' etc.
+KOLLA_OPENSTACK_RELEASE = 'master'
+
+if KOLLA_OPENSTACK_RELEASE == 'master':
+    KOLLA_BRANCH_NAME = KOLLA_OPENSTACK_RELEASE
+else:
+    KOLLA_BRANCH_NAME = 'stable/{}'.format(KOLLA_OPENSTACK_RELEASE)
+
+GLOBAL_VARIABLE_MAP = {
+    "|KOLLA_ANSIBLE_MAJOR_VERSION|": KOLLA_ANSIBLE_MAJOR_VERSION,
+    "|KOLLA_OPENSTACK_RELEASE|": KOLLA_OPENSTACK_RELEASE,
+    "|KOLLA_BRANCH_NAME|": KOLLA_BRANCH_NAME,
+}
+
+def replace_global_vars(app, docname, source):
+    # unlike rst_epilog, replaces variables (strings) in code blocks as well
+    # thanks to https://github.com/sphinx-doc/sphinx/issues/4054#issuecomment-329097229
+    result = source[0]
+    for key in app.config.GLOBAL_VARIABLE_MAP:
+        result = result.replace(key, app.config.GLOBAL_VARIABLE_MAP[key])
+    source[0] = result
+
+
+def setup(app):
+   app.add_config_value('GLOBAL_VARIABLE_MAP', {}, True)
+   app.connect('source-read', replace_global_vars)
diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
index 2d79ba5e36..9d2318c2e2 100644
--- a/doc/source/user/quickstart.rst
+++ b/doc/source/user/quickstart.rst
@@ -149,19 +149,23 @@ Install Kolla-ansible
 Install Kolla-ansible for deployment or evaluation
 --------------------------------------------------
 
+For a list of ``kolla-ansible`` versions compatible with each OpenStack release
+see `Kolla Ansible release notes
+<https://docs.openstack.org/releasenotes/kolla-ansible/>`__.
+
 #. Install kolla-ansible and its dependencies using ``pip``.
 
    If using a virtual environment:
 
    .. code-block:: console
 
-      pip install kolla-ansible
+      pip install 'kolla-ansible == |KOLLA_ANSIBLE_MAJOR_VERSION|.*'
 
    If not using a virtual environment:
 
    .. code-block:: console
 
-      sudo pip3 install kolla-ansible
+      sudo pip3 install 'kolla-ansible == |KOLLA_ANSIBLE_MAJOR_VERSION|.*'
 
 #. Create the ``/etc/kolla`` directory.
 
@@ -206,8 +210,8 @@ Install Kolla for development
 
    .. code-block:: console
 
-      git clone https://github.com/openstack/kolla
-      git clone https://github.com/openstack/kolla-ansible
+      git clone --branch |KOLLA_BRANCH_NAME| https://opendev.org/openstack/kolla
+      git clone --branch |KOLLA_BRANCH_NAME| https://opendev.org/openstack/kolla-ansible
 
 #. Install requirements of ``kolla`` and ``kolla-ansible``: