Docs: use extrefs to link to other projects' docs

This feature of openstackdocstheme means that we'll always link to the
corresponding branch of another project (i.e. latest links to latest,
but train links to train, &c.)

https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper

Change-Id: If94115f87af3689413405f3283be7fb197fab058
(cherry picked from commit dd70d9244d5a8b8b91b3e5908b45bf5b7f6a8974)

12 files changed, 74 insertions, 70 deletions

diff --git a/doc/source/admin/auth-model.rst b/doc/source/admin/auth-model.rst
index 45effc556..3c404e971 100644
--- a/doc/source/admin/auth-model.rst
+++ b/doc/source/admin/auth-model.rst
@@ -77,7 +77,8 @@ which is consumed by *only* the trustee to obtain a
 such that the trustee has limited access to those
 roles delegated. In addition, the trustee has effective impersonation
 of the trustor user if it was selected when creating the trust.
-For more information, see `Identity Management trusts`_.
+For more information, see :keystone-doc:`Identity management trusts
+<admin/identity-use-trusts.html>`.
 
 Trusts authorization involves the following steps:
 
@@ -146,5 +147,3 @@ defined, then all the trustor roles are delegated to trustee.
 
    The trustor delegated roles must be pre-configured in the
    OpenStack Identity service before using them in the Orchestration service.
-
-.. _Identity management trusts: https://docs.openstack.org/keystone/latest/admin/identity-use-trusts.html
diff --git a/doc/source/admin/introduction.rst b/doc/source/admin/introduction.rst
index 61187b9c5..a66673413 100644
--- a/doc/source/admin/introduction.rst
+++ b/doc/source/admin/introduction.rst
@@ -28,5 +28,5 @@ integrated with the OpenStack dashboard to perform stack functions through
 a web interface.
 
 For more information about using the Orchestration service through the
-command line, see the `Heat Command-Line Interface reference
-<https://docs.openstack.org/python-heatclient/latest/#openstackclient-command-line>`_.
+command line, see the :python-heatclient-doc:`Heat Command-Line Interface
+reference <#openstackclient-command-line>`.
diff --git a/doc/source/admin/stack-domain-users.rst b/doc/source/admin/stack-domain-users.rst
index f5f043bc7..fa869d943 100644
--- a/doc/source/admin/stack-domain-users.rst
+++ b/doc/source/admin/stack-domain-users.rst
@@ -125,7 +125,8 @@ The following steps are run during stack creation:
    in the stack domain are still assigned the ``heat_stack_user`` role, so
    the API surface they can access is limited through
    the :file:`policy.json` file.
-   For more  information, see `OpenStack Identity documentation`_.
+   For more  information, see :keystone-doc:`OpenStack Identity documentation
+   <>`.
 
 #. When API requests are processed, the Orchestration service performs
    an internal lookup, and allows stack details for a given stack to be
@@ -149,5 +150,3 @@ or::
 The stack owner uses the former (via ``openstack stack resource metadata
 STACK RESOURCE``), and any agents in the instance
 use the latter.
-
-.. _OpenStack Identity documentation: https://docs.openstack.org/keystone/latest/
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1342c5be7..c5b0821ef 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -100,6 +100,19 @@ bug_tag = 'docs'
 
 todo_include_todos = True
 
+# openstackdocstheme external link helper projects
+openstack_projects = [
+    'devstack',
+    'diskimage-builder',
+    'keystone',
+    'keystoneauth',
+    'nova',
+    'oslo.reports',
+    'python-barbicanclient',
+    'python-heatclient',
+    'python-openstackclient',
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
 
diff --git a/doc/source/developing_guides/gmr.rst b/doc/source/developing_guides/gmr.rst
index f2daeaae8..26d1d41f7 100644
--- a/doc/source/developing_guides/gmr.rst
+++ b/doc/source/developing_guides/gmr.rst
@@ -90,4 +90,4 @@ Extending the GMR
 
 As mentioned above, additional sections can be added to the GMR for a
 particular executable. For more information, see the documentation about
-`oslo.reports <https://docs.openstack.org/oslo.reports/>`_
+:oslo.reports-doc:`oslo.reports <>`.
diff --git a/doc/source/getting_started/create_a_stack.rst b/doc/source/getting_started/create_a_stack.rst
index 8b8f03dac..0d1576a92 100644
--- a/doc/source/getting_started/create_a_stack.rst
+++ b/doc/source/getting_started/create_a_stack.rst
@@ -118,8 +118,7 @@ Note: The list operation will show no running stack.::
     $ openstack stack delete teststack
     $ openstack stack list
 
-You can explore other heat commands by referring to the `Heat command reference
-<https://docs.openstack.org/python-heatclient/latest/cli/>`_ for the
-`OpenStack Command-Line Interface
-<https://docs.openstack.org/python-openstackclient/>`_; then read the
-:ref:`template-guide` and start authoring your own templates.
+You can explore other heat commands by referring to the
+:python-heatclient-doc:`Heat command reference <cli/>` for the
+:python-openstackclient-doc:`OpenStack Command-Line Interface <>`; then read
+the :ref:`template-guide` and start authoring your own templates.
diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
index 304bc1b46..316a3c9db 100644
--- a/doc/source/glossary.rst
+++ b/doc/source/glossary.rst
@@ -57,10 +57,9 @@
 
    Metadata service
      A Compute service that enables virtual machine instances to
-     retrieve instance-specific data. See `Metadata
-     service (OpenStack Administrator Guide)`_.
-
-     .. _Metadata service (OpenStack Administrator Guide): https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service
+     retrieve instance-specific data. See :nova-doc:`Metadata
+     service (OpenStack Administrator Guide)
+     <admin/networking-nova.html#metadata-service>`.
 
    Multi-region
      A feature of Heat that supports deployment to multiple regions.
@@ -162,10 +161,9 @@
    User data
      A :term:`resource property` that contains a user-provided data
      blob. User data gets passed to `cloud-init`_ to automatically
-     configure instances at boot time. See also `User data (OpenStack
-     End User Guide)`_.
+     configure instances at boot time. See also :nova-doc:`User data
+     (OpenStack End User Guide) <user/user-data.html>`.
 
-     .. _User data (OpenStack End User Guide): https://docs.openstack.org/nova/latest/user/user-data.html
      .. _cloud-init: https://cloudinit.readthedocs.io/
 
    Wait condition
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0f8755294..956eaf32d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -80,10 +80,9 @@ Using the Heat Service
 ----------------------
 
 - `OpenStack Orchestration API v1 Reference`_
-- `Python and CLI client`_
+- :python-heatclient-doc:`Python and CLI client <>`
 
 .. _`OpenStack Orchestration API v1 Reference`: https://docs.openstack.org/api-ref/orchestration/v1/
-.. _`Python and CLI client`: https://docs.openstack.org/python-heatclient/latest
 
 Developing Heat
 ===============
diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst
index 54072ed4a..e5bfae0e7 100644
--- a/doc/source/install/install-rdo.rst
+++ b/doc/source/install/install-rdo.rst
@@ -74,14 +74,13 @@ requires additional information in the Identity service.
 
      .. note::
 
-        If installing OpenStack manually following the `Keystone install
-        guide`_, the name of the services project is ``service`` as given
-        above. However, traditional methods of installing RDO (such as
-        PackStack and TripleO) use ``services`` as the name of the service
-        project. If you installed RDO using a Puppet-based method, substitute
-        ``services`` as the project name.
-
-     .. _`Keystone install guide`: https://docs.openstack.org/keystone/latest/install/keystone-users-rdo.html
+        If installing OpenStack manually following the :keystone-doc:`Keystone
+        install guide <install/keystone-users-rdo.html>`, the name of the
+        services project is ``service`` as given above. However, traditional
+        methods of installing RDO (such as PackStack and TripleO) use
+        ``services`` as the name of the service project. If you installed RDO
+        using a Puppet-based method, substitute ``services`` as the project
+        name.
 
      .. note::
 
diff --git a/doc/source/operating_guides/scale_deployment.rst b/doc/source/operating_guides/scale_deployment.rst
index c19d3657f..0e79fab83 100644
--- a/doc/source/operating_guides/scale_deployment.rst
+++ b/doc/source/operating_guides/scale_deployment.rst
@@ -31,12 +31,12 @@ Assumptions
 
 This guide, using a devstack installation of OpenStack, assumes that:
 
-    1. You have configured devstack from `Single Machine Installation Guide
-       <https://docs.openstack.org/devstack/latest/guides/single-machine.html>`_;
-    2. You have set up heat on devstack, as defined at :doc:`heat and DevStack
-       <../getting_started/on_devstack>`;
-    3. You have installed HAProxy_ on the devstack
-       server.
+1. You have configured devstack from :devstack-doc:`Single Machine
+   Installation Guide <guides/single-machine.html>`;
+2. You have set up heat on devstack, as defined at :doc:`heat and DevStack
+   <../getting_started/on_devstack>`;
+3. You have installed HAProxy_ on the devstack
+   server.
 
 Architecture
 ============
diff --git a/doc/source/template_guide/multi-clouds.rst b/doc/source/template_guide/multi-clouds.rst
index 6509d1a08..e6266db46 100644
--- a/doc/source/template_guide/multi-clouds.rst
+++ b/doc/source/template_guide/multi-clouds.rst
@@ -13,10 +13,10 @@ multi-clouds features, and what's the environment requirement.
 
 .. note:: If you like to create a stack in multi-region environment,
   you don't need this feature at all. all you need to do is provide
-  `region_name` under `context` property for `OS::Heat::Stack`_.
+  `region_name` under `context` property for :ref:`OS::Heat::Stack`.
   If you like to see information on how to provide SSL support for
   your multi-region environment, you can jump to `Use CA
-  cert(Optional)`_ .
+  cert (Optional)`_ .
 
 Requirements
 ~~~~~~~~~~~~
@@ -58,17 +58,23 @@ Gathering credential information
 Before we start generating secret, let's talk about what credential format we
 need. credential is a JSON format string contains two keys ``auth_type``, and
 ``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from
-Keystone. You can find `plugin options`_  and `authentication plugins`_ in
-keystoneauth documents.
+Keystone. You can find :keystoneauth-doc:`plugin options
+<plugin-options.html>` and :keystoneauth-doc:`authentication plugins
+<authentication-plugins.html#loading-plugins-by-name>` in keystoneauth
+documents.
 
 * **auth_type** - ``auth_type`` is a string for plugin name. Allows value like
   `v3applicationcredential`, `password`, `v3oidcclientcredentials`, etc. You
-  need to provide `available plugins`_.
+  need to provide `available plugins
+  <plugin-options.html#available-plugins>`.
 
 * **auth** - auth is a dictionary contains all parameters for plugins to
   perform authentication. You can find all valid parameter references from
-  `available plugins`_ or get to all class path from `plugin names`_ for more
-  detail allowed value or trace plugin class from there.
+  :keystoneauth-doc:`available plugins
+  <plugin-options.html#available-plugins>` or get to all class path from
+  :keystoneauth-doc:`plugin names
+  <authentication-plugins.html#loading-plugins-by-name>` for more detail
+  allowed value or trace plugin class from there.
 
 As you can tell, all allowed authentication plugins for credentials follows
 plugins keystoneauth rules. So once new change in keystoneauth, it will also
@@ -81,15 +87,18 @@ Validate your credential
 ------------------------
 
 Now you have all your credential information ready, try to validate first if
-you can. You can either directly test them `via config`_, `via CLI`_, or
-`via keystoneauth sessions`_.
+you can. You can either directly test them :keystoneauth-doc:`via config
+<plugin-options.html#using-plugins-via-config-file>`,
+:keystoneauth-doc:`via CLI <plugin-options.html#using-plugins-via-cli>`,
+or :keystoneauth-doc:`via keystoneauth sessions <using-sessions.html>`.
 
 build credential secret
 -----------------------
 
-Once you're sure it's valid, we can start building the secret out.
-To build a secret you just have to follow standard Barbican CLI_ or API to
-store your secret.
+Once you're sure it's valid, we can start building the secret out. To build a
+secret you just have to follow the standard
+:python-barbicanclient-doc:`Barbican CLI <cli/cli_usage.html#secret-create>` or
+API to store your secret.
 
 The local site will read this secret to perform stack actions in remote site.
 Let's give a quick example here:
@@ -111,9 +120,8 @@ Create remote stacks
 Now, you have a secret id generated for your Barbican secret. Use that id as
 input for template.
 
-To create a remote stack, you can simply use `OS::Heat::Stack`_ resource, as
-child stack in your template (we also referring this structure as
-`nested stack`).
+To create a remote stack, you can simply use an :ref:`OS::Heat::Stack` resource
+in your template.
 
 In resource properties, provide `credential_secret_id` (Barbican secret ID
 from the secret we just builded for credential) under `context` property.
@@ -146,8 +154,8 @@ won't affect resources/stacks in remote site. So do such actions with super
 care.
 
 
-Use CA cert(Optional)
----------------------
+Use CA cert (Optional)
+----------------------
 
 For production clouds, it's very important to have SSL support. Here we
 provide CA cert method for your SSL access. If you wish to use that, use
@@ -174,13 +182,3 @@ Here is an example for you:
         template: { get_file: "remote-app.yaml" }
 
 .. note:: If insecure flag is on, ca_cert will be ignored.
-
-.. _`plugin options`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html
-.. _`authentication plugins`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
-.. _`plugin names`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
-.. _`available plugins`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#available-plugins
-.. _`via keystoneauth sessions`: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
-.. _`via config`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-config-file
-.. _`via CLI`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-cli
-.. _CLI: https://docs.openstack.org/python-barbicanclient/latest/cli/cli_usage.html#secret-create
-.. _`OS::Heat::Stack`: https://docs.openstack.org/heat/rocky/template_guide/openstack.html#OS::Heat::Stack
diff --git a/doc/source/template_guide/software_deployment.rst b/doc/source/template_guide/software_deployment.rst
index 7f989f8d0..8f3accebb 100644
--- a/doc/source/template_guide/software_deployment.rst
+++ b/doc/source/template_guide/software_deployment.rst
@@ -39,18 +39,21 @@ you might want to do this, including:
 
 A number of tools are available for building custom images, including:
 
-* diskimage-builder_ image building tools for OpenStack
+* :diskimage-builder-doc:`diskimage-builder <>` image building tools for OpenStack
 
 * imagefactory_ builds images for a variety of operating system/cloud
   combinations
 
-Examples in this guide which require custom images will use diskimage-builder_.
+Examples in this guide that require custom images will use
+:diskimage-builder-doc:`diskimage-builder <>`.
 
 User-data boot scripts and cloud-init
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 When booting a server it is possible to specify the contents of the user-data
 to be passed to that server. This user-data is made available either from
-configured config-drive or from the `Metadata service`_.
+configured config-drive or from the :nova-doc:`Metadata service
+<admin/networking-nova.html#metadata-service>`
 
 How this user-data is consumed depends on the image being booted, but the most
 commonly used tool for default cloud images is cloud-init_.
@@ -779,11 +782,8 @@ contents of the file ``example-puppet-manifest.pp``, containing:
     }
 
 
-
 .. _`AWS::CloudFormation::Init`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-init.html
-.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
 .. _imagefactory: https://imgfac.org/
-.. _`Metadata service`: https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service
 .. _cloud-init: https://cloudinit.readthedocs.io/
 .. _curl: https://curl.haxx.se/
 .. _`Orchestration API`: https://docs.openstack.org/api-ref/orchestration/v1/