diff --git a/doc/source/administration/overcloud.rst b/doc/source/administration/overcloud.rst
index 30082cceb29c37e1489e829bb35db1355e2be6c5..a3d498eaa8b4880e52ccf744c00ddac51494071f 100644
--- a/doc/source/administration/overcloud.rst
+++ b/doc/source/administration/overcloud.rst
@@ -188,5 +188,5 @@ Or to perform an incremental backup, run the following command:
kayobe overcloud database backup --incremental
Further information on backing up and restoring the database is available in
-the `Kolla Ansible documentation
-<https://docs.openstack.org/kolla-ansible/latest/admin/mariadb-backup-and-restore.html>`__.
+the :kolla-ansible-doc:`Kolla Ansible documentation
+<admin/mariadb-backup-and-restore.html>`.
diff --git a/doc/source/configuration/hosts.rst b/doc/source/configuration/hosts.rst
index 9b8cf3d125b077a3e2ec1cb50eb89765a3bd1c65..d2b45dffd47b22e31c31ec765d84448b9016e203 100644
--- a/doc/source/configuration/hosts.rst
+++ b/doc/source/configuration/hosts.rst
@@ -607,8 +607,8 @@ bootstrapping nature of the command, Kayobe uses ``kayobe_ansible_user`` to
execute it, and uses the Kayobe remote Python virtual environment (or the
system Python interpreter if no virtual environment is in use).
-See the `Kolla Ansible documentation
-<https://docs.openstack.org/kolla-ansible/latest/reference/deployment-and-bootstrapping/bootstrap-servers.html>`__
+See the :kolla-ansible-doc:`Kolla Ansible documentation
+<reference/deployment-and-bootstrapping/bootstrap-servers.html>`
for more information on the functions performed by this command, and how to
configure it.
diff --git a/doc/source/configuration/kolla-ansible.rst b/doc/source/configuration/kolla-ansible.rst
index 49dda645ea3fc5a377616c71fff28543a8e4a4f9..6c8b56a1455b4b9502c9d01eb154d94d4f70a98e 100644
--- a/doc/source/configuration/kolla-ansible.rst
+++ b/doc/source/configuration/kolla-ansible.rst
@@ -70,9 +70,8 @@ Control Plane Services
Kolla-ansible provides a flexible mechanism for configuring the services that
it deploys. Kayobe adds some commonly required configuration options to the
defaults provided by kolla-ansible, but also allows for the free-form
-configuration supported by kolla-ansible. The `kolla-ansible documentation
-<https://docs.openstack.org/kolla-ansible/latest/>`_ should be used as a
-reference.
+configuration supported by kolla-ansible. The :kolla-ansible-doc:`kolla-ansible
+documentation <>` should be used as a reference.
Global Variables
----------------
@@ -128,9 +127,9 @@ variable ``kolla_ansible_custom_passwords`` in
Service Configuration
---------------------
-Kolla-ansible's flexible configuration is described in the `kolla-ansible
-service configuration documentation
-<https://docs.openstack.org/kolla-ansible/latest/admin/advanced-configuration.html#openstack-service-configuration-in-kolla>`_.
+Kolla-ansible's flexible configuration is described in the
+:kolla-ansible-doc:`kolla-ansible service configuration documentation
+<admin/advanced-configuration.html#openstack-service-configuration-in-kolla>`.
We won't duplicate that here, but essentially it involves creating files under
a directory which for users of kayobe will be ``$KOLLA_CONFIG_PATH/config``. In
kayobe, files in this directory are auto-generated and managed by kayobe.
diff --git a/doc/source/configuration/kolla.rst b/doc/source/configuration/kolla.rst
index e3b973105700825414271f68348d2d4dc24f4ee9..bdae872ef5d9129aabe349fe2334d16677faab32 100644
--- a/doc/source/configuration/kolla.rst
+++ b/doc/source/configuration/kolla.rst
@@ -5,8 +5,7 @@ Kolla Configuration
===================
Anyone using Kayobe to build images should familiarise themselves with the
-`Kolla project's documentation
-<https://docs.openstack.org/kolla/latest/>`__.
+:kolla-doc:`Kolla project's documentation <>`.
Container Image Build Host
==========================
@@ -163,9 +162,8 @@ Overriding Jinja2 blocks
Kolla's images are defined via Jinja2 templates that generate Dockerfiles.
Jinja2 blocks are frequently used to allow specific statements in one or more
-Dockerfiles to be replaced with custom statements. See the `Kolla documentation
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#generic-customisation>`__
-for details.
+Dockerfiles to be replaced with custom statements. See the :kolla-doc:`Kolla
+documentation <admin/image-building.html#generic-customisation>` for details.
Blocks are configured via the ``kolla_build_blocks`` variable, which is a dict
mapping Jinja2 block names in to their contents.
@@ -195,11 +193,10 @@ following content:
Overriding Jinja2 variables
---------------------------
-Jinja2 variables offer another way to customise images. See the `Kolla
-documentation
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#package-customisation>`__
-for details of using variable overrides to modify the list of packages to
-install in an image.
+Jinja2 variables offer another way to customise images. See the
+:kolla-doc:`Kolla documentation
+<admin/image-building.html#package-customisation>` for details of using
+variable overrides to modify the list of packages to install in an image.
Variable overrides are configured via the ``kolla_build_customizations``
variable, which is a dict/map mapping names of variables to override to their
@@ -234,10 +231,10 @@ Source code locations
For ``source`` image builds, configuration of source code locations for
packages installed in containers by Kolla is possible via the ``kolla_sources``
variable. The format is a dict/map mapping names of sources to their
-definitions. See the `Kolla documentation
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#build-openstack-from-source>`__
-for details. The default is to specify the URL and version of Bifrost, as
-defined in ``${KAYOBE_CONFIG_PATH}/bifrost.yml``.
+definitions. See the :kolla-doc:`Kolla documentation
+<admin/image-building.html#build-openstack-from-source>` for details. The
+default is to specify the URL and version of Bifrost, as defined in
+``${KAYOBE_CONFIG_PATH}/bifrost.yml``.
For example, to specify a custom source location for the ``ironic-base``
package:
@@ -277,11 +274,9 @@ using a seed.
Plugins & additions
-------------------
-These features can also be used for installing `plugins
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#plugin-functionality>`__
-and `additions
-<https://docs.openstack.org/kolla/latest/admin/image-building.html#additions-functionality>`__
-to ``source`` type images.
+These features can also be used for installing :kolla-doc:`plugins
+<admin/image-building.html#plugin-functionality>` and :kolla-doc:`additions
+<admin/image-building.html#additions-functionality>` to ``source`` type images.
For example, to install a ``networking-ansible`` plugin in the
``neutron-server`` image:
diff --git a/doc/source/upgrading.rst b/doc/source/upgrading.rst
index 33947bf2b04773efb80d1d685d86288ff36cdc10..5d4438c573337c9c4d51d00732ee47aad9ec48de 100644
--- a/doc/source/upgrading.rst
+++ b/doc/source/upgrading.rst
@@ -270,11 +270,11 @@ in the Queens release, and `removed
<https://docs.openstack.org/releasenotes/ironic/rocky.html#relnotes-11-0-0-stable-rocky-upgrade-notes>`__
in the Rocky release. Nodes registered with ironic in Pike and earlier releases
of Bifrost use the classic drivers by default, and will need to be migrated to
-use the new hardware types. The `ironic documentation
-<https://docs.openstack.org/ironic/latest/admin/upgrade-to-hardware-types.html>`__
-provides details for how to do this, but for the default case of the
-``agent_ipmitool`` driver the following procedure may be used, replacing
-``<node>`` with the name of the host to migrate:
+use the new hardware types. The :ironic-doc:`ironic documentation
+<admin/upgrade-to-hardware-types.html>` provides details for how to do this,
+but for the default case of the ``agent_ipmitool`` driver the following
+procedure may be used, replacing ``<node>`` with the name of the host to
+migrate:
.. code-block:: console