From c9cc6f4064ab2f1edeb15f86bd9db5d65e88c4df Mon Sep 17 00:00:00 2001 From: Mark Goddard 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 `_ 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 /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 $ mkdir -p src venvs -Next, obtain the Kayobe source code. For example:: +Next, obtain the Kayobe source code. For example: - $ cd /src - $ git clone https://opendev.org/openstack/kayobe.git +.. parsed-literal:: + + $ cd /src + $ git clone \https://opendev.org/openstack/kayobe.git -b |current_release_git_branch_name| Create a virtualenv for Kayobe::