From c9cc6f4064ab2f1edeb15f86bd9db5d65e88c4df Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Thu, 29 Apr 2021 10:35:54 +0100
Subject: [PATCH] docs: add variable for current branch
This allows us to include the correct branch when cloning repositories
in documentation.
Method adapted from OpenStack Ansible documentation. A backslash is
added on purpose before repository URLs to bypass highlighting which
makes them less readable (dark text on dark background).
https://opendev.org/openstack/openstack-ansible/src/branch/master/doc/source/conf.py
Story: 2008851
Task: 42366
Change-Id: I4b4a8d1c848bb992f65860b058cb9fd9d77613d0
---
doc/source/conf.py | 22 +++++++++++++++
.../scenarios/all-in-one/overcloud.rst | 6 ++--
doc/source/contributor/automated.rst | 28 ++++++++++++-------
doc/source/contributor/testing.rst | 12 ++++----
doc/source/contributor/vagrant.rst | 6 ++--
doc/source/installation.rst | 8 ++++--
6 files changed, 59 insertions(+), 23 deletions(-)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 97764ddd4..d29788c51 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -26,6 +26,28 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+import openstackdocstheme
+
+
+# -- Kayobe configuration --------------------------------------
+# Variables to override
+
+# 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":
+ branch = "master"
+else:
+ branch = "stable/{}".format(current_series)
+
+# Substitutions loader
+rst_epilog = """
+.. |current_release_git_branch_name| replace:: {current_release_git_branch_name}
+""".format( # noqa: E501
+ current_release_git_branch_name=branch,
+)
+
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
diff --git a/doc/source/configuration/scenarios/all-in-one/overcloud.rst b/doc/source/configuration/scenarios/all-in-one/overcloud.rst
index c91621ecc..d6085f31d 100644
--- a/doc/source/configuration/scenarios/all-in-one/overcloud.rst
+++ b/doc/source/configuration/scenarios/all-in-one/overcloud.rst
@@ -21,12 +21,12 @@ Configuration
Clone the `kayobe-config <https://opendev.org/openstack/kayobe-config>`_
git repository, using the correct branch for the release you are deploying. In
-this example we will use the ``master`` branch.
+this example we will use the |current_release_git_branch_name| branch.
-.. code-block:: console
+.. parsed-literal::
cd <base path>/src
- git clone https://opendev.org/openstack/kayobe-config -b master
+ git clone \https://opendev.org/openstack/kayobe-config.git -b |current_release_git_branch_name|
cd kayobe-config
This repository is bare, and needs to be populated. The repository includes an
diff --git a/doc/source/contributor/automated.rst b/doc/source/contributor/automated.rst
index 5e2455819..76ce1fde9 100644
--- a/doc/source/contributor/automated.rst
+++ b/doc/source/contributor/automated.rst
@@ -42,18 +42,22 @@ Overcloud
Preparation
-----------
-Clone the Kayobe repository::
+Clone the Kayobe repository:
- git clone https://opendev.org/openstack/kayobe.git
+.. parsed-literal::
+
+ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name|
Change the current directory to the Kayobe repository::
cd kayobe
-Clone the ``kayobe-config-dev`` repository to ``config/src/kayobe-config``::
+Clone the ``kayobe-config-dev`` repository to ``config/src/kayobe-config``
- mkdir -p config/src
- git clone https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config
+.. parsed-literal::
+
+ mkdir -p config/src
+ git clone \https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config -b |current_release_git_branch_name|
Inspect the Kayobe configuration and make any changes necessary for your
environment.
@@ -191,18 +195,22 @@ VM.
Preparation
-----------
-Clone the Kayobe repository::
+Clone the Kayobe repository:
- git clone https://opendev.org/openstack/kayobe.git
+.. parsed-literal::
+
+ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name|
Change to the ``kayobe`` directory::
cd kayobe
-Clone the ``kayobe-config-dev`` repository to ``config/src/kayobe-config``::
+Clone the ``kayobe-config-dev`` repository to ``config/src/kayobe-config``:
- mkdir -p config/src
- git clone https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config
+.. parsed-literal::
+
+ mkdir -p config/src
+ git clone \https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config -b |current_release_git_branch_name|
Inspect the Kayobe configuration and make any changes necessary for your
environment.
diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst
index d27143b8e..8c1e3d988 100644
--- a/doc/source/contributor/testing.rst
+++ b/doc/source/contributor/testing.rst
@@ -44,12 +44,14 @@ Running Unit Tests Locally
==========================
If you haven't already, the kayobe source code should be pulled directly from
-git::
+git:
- # from your home or source directory
- cd ~
- git clone https://opendev.org/openstack/kayobe.git
- cd kayobe
+.. parsed-literal::
+
+ # from your home or source directory
+ cd ~
+ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name|
+ cd kayobe
Running Unit and Style Tests
----------------------------
diff --git a/doc/source/contributor/vagrant.rst b/doc/source/contributor/vagrant.rst
index 1613f8f1c..c967a051f 100644
--- a/doc/source/contributor/vagrant.rst
+++ b/doc/source/contributor/vagrant.rst
@@ -37,9 +37,11 @@ Later sections in the development guide cover in more detail how to use the
development VM in different configurations. These steps cover bringing up and
accessing the VM.
-Clone the kayobe repository::
+Clone the kayobe repository:
- git clone https://opendev.org/openstack/kayobe.git
+.. parsed-literal::
+
+ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name|
Change the current directory to the kayobe repository::
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index befafc3cc..e71d1e0e3 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -127,10 +127,12 @@ code repositories and python virtual environments::
$ cd <base_path>
$ mkdir -p src venvs
-Next, obtain the Kayobe source code. For example::
+Next, obtain the Kayobe source code. For example:
- $ cd <base_path>/src
- $ git clone https://opendev.org/openstack/kayobe.git
+.. parsed-literal::
+
+ $ cd <base_path>/src
+ $ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name|
Create a virtualenv for Kayobe::