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)

10 files changed, 42 insertions, 35 deletions

diff --git a/doc/source/admin/auth-model.rst b/doc/source/admin/auth-model.rst
index 4c7373103..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 04bfe1d79..f4023c7e8 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -102,6 +102,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 002853f3a..f2cb1c0cd 100644
--- a/doc/source/getting_started/create_a_stack.rst
+++ b/doc/source/getting_started/create_a_stack.rst
@@ -114,8 +114,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 8b65d3bb8..5d40296d1 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://developer.openstack.org/api-ref/orchestration/v1/
-.. _`Python and CLI client`: https://docs.openstack.org/python-heatclient/latest
 
 Developing Heat
 ===============
diff --git a/doc/source/operating_guides/scale_deployment.rst b/doc/source/operating_guides/scale_deployment.rst
index ffcc77d62..a054352e8 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/software_deployment.rst b/doc/source/template_guide/software_deployment.rst
index 4e47c58e0..772714b15 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://developer.openstack.org/api-ref/orchestration/v1/