Comment 5 for bug 1844710

I've been working a bit on this issue and turns out that global variable substitution in Sphinx reST is more complicated (than it should).

Based on:

https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog

and

https://opendev.org/openstack/openstack-ansible/src/commit/5a8e199ca1ac525c1f6a5a5c3d61964f2393dfce/deploy-guide/source/conf.py#L59

I've added in doc/source/conf.py:

rst_epilog = """
.. |MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE| replace:: {MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE}
.. |MAX_ANSIBLE_VER_EXCLUSIVE| replace:: {MAX_ANSIBLE_VER_EXCLUSIVE}
.. |KOLLA_GIT_BRANCH| replace:: {KOLLA_GIT_BRANCH}
.. |KOLLA_ANSIBLE_GIT_BRANCH| replace:: {KOLLA_ANSIBLE_GIT_BRANCH}
""".format(
    MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE=MAX_KOLLA_ANSIBLE_VER_EXCLUSIVE,
    MAX_ANSIBLE_VER_EXCLUSIVE=MAX_ANSIBLE_VER_EXCLUSIVE,
    KOLLA_GIT_BRANCH=KOLLA_GIT_BRANCH,
    KOLLA_ANSIBLE_GIT_BRANCH=KOLLA_ANSIBLE_GIT_BRANCH
)

But unfortunately variables are not replaced in code blocks like this:

   .. code-block:: console

      git clone --branch |KOLLA_GIT_BRANCH| https://opendev.org/openstack/kolla
      git clone --branch |KOLLA_ANSIBLE_GIT_BRANCH| https://opendev.org/openstack/kolla-ansible

also according to https://stackoverflow.com/questions/42158111/variable-substitution-not-working-properly-in-sphinx

Two possible solutions in that thread, neither great:

Option 1: use .. parsed-literal:: instead of .. code-block:: , but this makes the code block have different styling from other code blocks (different text color) and hyperlinks become clickable: https://ibb.co/9VP61vx

Option 2: add a docs dependency lib: https://github.com/adamtheturtle/sphinx-substitution-extensions

Anyone has a better idea?