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

@@ -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)

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``: