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

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

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

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``
+
+.. parsed-literal::
 
-    mkdir -p config/src
-    git clone https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config
+   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``:
+
+.. parsed-literal::
 
-    mkdir -p config/src
-    git clone https://opendev.org/openstack/kayobe-config-dev.git config/src/kayobe-config
+   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.

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

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

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