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 2ba4adf39c2d89c463c0165d574161502be7846b..6f2fa96590dc52dd7684f5504280a72edbba6755 100644
--- a/doc/source/configuration/hosts.rst
+++ b/doc/source/configuration/hosts.rst
@@ -605,8 +605,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 600a35a3aa9eb0b64ec86cb8a6500fcaa58cc3bd..646adea5d51b33f777d1514e7f00fa43ac7241eb 100644
--- a/doc/source/configuration/kolla-ansible.rst
+++ b/doc/source/configuration/kolla-ansible.rst
@@ -68,9 +68,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
----------------
@@ -126,9 +125,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 3273f4a7c11a63f6ed341350f3944868b9477de5..2dc0106ca0bfe781ada782b3779da9ce97552226 100644
--- a/doc/source/configuration/kolla.rst
+++ b/doc/source/configuration/kolla.rst
@@ -3,8 +3,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
==========================
@@ -160,9 +159,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.
@@ -192,11 +190,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
@@ -231,10 +228,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:
@@ -274,11 +271,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 cf0be2707f03879eafa004d6d7f04d1b161c5061..e9d79231da713454dd30724c242aced0323857c7 100644
--- a/doc/source/upgrading.rst
+++ b/doc/source/upgrading.rst
@@ -236,11 +236,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