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 8f1562ef0..620cb84a7 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 2d79ba5e3..9d2318c2e 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``:
--
GitLab