Merge "Docs: Make robust with using real links" into stable/stein

37 files changed, 138 insertions, 96 deletions

diff --git a/doc/source/admin/caching-layer.rst b/doc/source/admin/caching-layer.inc
index 419791073..400b6e869 100644
--- a/doc/source/admin/caching-layer.rst
+++ b/doc/source/admin/caching-layer.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 Caching layer
 =============
 
diff --git a/doc/source/admin/configuration.rst b/doc/source/admin/configuration.rst
index 30e74c592..164d9e14f 100644
--- a/doc/source/admin/configuration.rst
+++ b/doc/source/admin/configuration.rst
@@ -3,19 +3,18 @@ Keystone Configuration
 ======================
 
 Information and recommendations for general configuration of keystone for
-keystone administrators. See the main `Configuration`_ section for
+keystone administrators. See the main :ref:`Configuration
+<keystone_configuration_options>` section for
 complete keystone configuration documentation and sample config files.
 
-.. _Configuration: ../configuration/index.html
-
-.. include:: troubleshoot.rst
-.. include:: logging.rst
-.. include:: domain-specific-config.rst
-.. include:: integrate-with-ldap.rst
-.. include:: caching-layer.rst
-.. include:: security-compliance.rst
-.. include:: performance.rst
-.. include:: url-safe-naming.rst
-.. include:: limit-list-size.rst
-.. include:: endpoint-filtering.rst
-.. include:: endpoint-policy.rst
+.. include:: troubleshoot.inc
+.. include:: logging.inc
+.. include:: domain-specific-config.inc
+.. include:: integrate-with-ldap.inc
+.. include:: caching-layer.inc
+.. include:: security-compliance.inc
+.. include:: performance.inc
+.. include:: url-safe-naming.inc
+.. include:: limit-list-size.inc
+.. include:: endpoint-filtering.inc
+.. include:: endpoint-policy.inc
diff --git a/doc/source/admin/domain-specific-config.rst b/doc/source/admin/domain-specific-config.inc
index aa6da27ed..3acc4f088 100644
--- a/doc/source/admin/domain-specific-config.rst
+++ b/doc/source/admin/domain-specific-config.inc
@@ -1,3 +1,7 @@
+.. -*- rst -*-
+
+.. _domain_specific_configuration:
+
 Domain-specific configuration
 =============================
 
diff --git a/doc/source/admin/endpoint-filtering.rst b/doc/source/admin/endpoint-filtering.inc
index 900eb1e3c..b27bf178d 100644
--- a/doc/source/admin/endpoint-filtering.rst
+++ b/doc/source/admin/endpoint-filtering.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 Endpoint Filtering
 ==================
 
diff --git a/doc/source/admin/endpoint-policy.rst b/doc/source/admin/endpoint-policy.inc
index f2ab9cce2..27fb62077 100644
--- a/doc/source/admin/endpoint-policy.rst
+++ b/doc/source/admin/endpoint-policy.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 Endpoint Policy
 ===============
 
diff --git a/doc/source/admin/event_notifications.rst b/doc/source/admin/event_notifications.rst
index 04e4c430f..9df8d50f8 100644
--- a/doc/source/admin/event_notifications.rst
+++ b/doc/source/admin/event_notifications.rst
@@ -158,7 +158,7 @@ The reason object will contain the following keys:
 * ``reasonCode``: HTTP response code for the event
 
 For more information, see
-:doc:`../admin/security-compliance`
+:ref:`security_compliance`
 for configuring PCI-DSS in keystone.
 
 Supported Events
diff --git a/doc/source/admin/federation/configure_federation.rst b/doc/source/admin/federation/configure_federation.rst
index 094229ee3..4fed147ea 100644
--- a/doc/source/admin/federation/configure_federation.rst
+++ b/doc/source/admin/federation/configure_federation.rst
@@ -26,7 +26,7 @@ Prerequisites
 -------------
 
 If you are not familiar with the idea of federated identity, see the
-`introduction`_ first.
+:ref:`federation_introduction` first.
 
 In this section, we will configure keystone as a Service Provider, consuming
 identity properties issued by an external Identity Provider, such as SAML
@@ -42,15 +42,18 @@ Ubuntu 16.04 and Apache 2.4.18.
 
 To enable federation, you'll need to run keystone behind a web server such as
 Apache rather than running the WSGI application directly with uWSGI or Gunicorn.
-See the installation guide for `SUSE`_, `RedHat`_ or `Ubuntu`_ to configure
-the Apache web server for keystone.
+See the installation guide for :ref:`SUSE <suse_configure_apache>`,
+:ref:`RedHat <redhat_configure_apache>` or :ref:`Ubuntu
+<ubuntu_configure_apache>` to configure the Apache web server for
+keystone.
 
 Throughout the rest of the guide, you will need to decide on three pieces of
 information and use them consistently throughout your configuration:
 
 1. The protocol name. This must be a valid keystone auth method and must match
-   one of: ``saml2``, ``openid``, ``mapped`` or a `custom auth method`_ for which
-   you must `register as an external driver`_.
+   one of: ``saml2``, ``openid``, ``mapped`` or a :ref:`custom auth
+   method <auth_plugins>` for which
+   you must :ref:`register as an external driver <developing_drivers>`.
 
 2. The identity provider name. This can be arbitrary.
 
@@ -71,13 +74,8 @@ Provider.
    ``/identity`` (for example), take this into account in your own
    configuration.
 
-.. _introduction: introduction
+
 .. _samltest.id: https://samltest.id
-.. _SUSE: ../../install/keystone-install-obs.html#configure-the-apache-http-server
-.. _RedHat: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
-.. _Ubuntu: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
-.. _custom auth method: ../../contributor/auth-plugins
-.. _register as an external driver: ../../contributor/developing-drivers
 
 Creating federation resources in keystone
 -----------------------------------------
@@ -133,6 +131,8 @@ See also the `API reference on identity providers`_.
 
 .. _API reference on identity providers: https://developer.openstack.org/api-ref/identity/v3-ext/#identity-providers
 
+.. _create_a_mapping:
+
 Create a Mapping
 ~~~~~~~~~~~~~~~~
 
@@ -236,12 +236,9 @@ Configuring an HTTPD auth module
 
 This guide currently only includes examples for the Apache web server, but it
 possible to use SAML, OpenIDC, and other auth modules in other web servers. See
-the installation guides for running keystone behind Apache for `SUSE`_,
-`RedHat`_ or `Ubuntu`_.
-
-.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
-.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
-.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
+the installation guides for running keystone behind Apache for
+:ref:`SUSE <suse_configure_apache>`, :ref:`RedHat
+<redhat_configure_apache>` or :ref:`Ubuntu <ubuntu_configure_apache>`.
 
 Configure protected endpoints
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -333,15 +330,13 @@ This guide contains examples for two major federation protocols:
 
 * SAML2.0 - see guides for the following implementations:
 
-  * `Set up mod_shib`_.
-  * `Set up mod_auth_mellon`_.
+  * :ref:`Set up mod_shib <shibboleth>`.
+  * :ref:`Set up mod_auth_mellon <mellon>`.
 
-* OpenID Connect: `Set up mod_auth_openidc`_.
+* OpenID Connect: :ref:`Set up mod_auth_openidc <federation_openidc>`.
 
-.. _`Set up mod_shib`: shibboleth.html
-.. _`Set up mod_auth_openidc`: openidc.html
-.. _`Set up mod_auth_mellon`: mellon.html
 
+.. _federation_configuring_keystone:
 
 Configuring Keystone
 --------------------
@@ -584,6 +579,8 @@ from the menu to be redirected to your Identity Provider for authentication.
    :height: 400px
    :alt: Horizon login screen using external authentication
 
+.. _keystone_as_idp:
+
 --------------------------------------
 Keystone as an Identity Provider (IdP)
 --------------------------------------
@@ -596,7 +593,7 @@ When keystone is configured as an Identity Provider, it is often referred to as
 clouds using the SAML2.0 protocol.
 
 If you are not familiar with the idea of federated identity, see the
-`introduction`_ first.
+:ref:`introduction <federation_introduction>` first.
 
 When setting up `Keystone to Keystone`, it is easiest to `configure a keystone
 Service Provider`_ first with a sandbox Identity Provider such as
@@ -758,6 +755,7 @@ to another cloud.
    :height: 175px
    :alt: Horizon dropdown menu for switching between keystone providers
 
-.. include:: openidc.rst
-.. include:: mellon.rst
-.. include:: shibboleth.rst
+.. include:: openidc.inc
+.. include:: mellon.inc
+.. include:: shibboleth.inc
+
diff --git a/doc/source/admin/federation/introduction.rst b/doc/source/admin/federation/introduction.rst
index c86adbdaa..52d32dd8b 100644
--- a/doc/source/admin/federation/introduction.rst
+++ b/doc/source/admin/federation/introduction.rst
@@ -14,6 +14,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _federation_introduction:
+
 Introduction to Keystone Federation
 ===================================
 
@@ -28,32 +30,31 @@ identity source and then provides keystone with a set of user attributes. This
 is useful if your organization already has a primary identity source since it
 means users don't need a separate set of credentials for the cloud. It is also
 useful for connecting multiple clouds together, as we can use a keystone in
-another cloud as an identity source. Using `LDAP as an identity backend`_ is
+another cloud as an identity source. Using :ref:`LDAP as an identity
+backend <integrate_with_ldap>` is
 another way for keystone to obtain identity information from an external source,
 but it requires keystone to handle passwords directly rather than offloading
 authentication to the external source.
 
 Keystone supports two configuration models for federated identity. The most
-common configuration is with `keystone as a Service Provider (SP)`_, using an
+common configuration is with :ref:`keystone as a Service Provider (SP)
+<keystone-as-sp>`, using an
 external Identity Provider, such as a Keycloak or Google, as the identity source
-and authentication method. The second type of configuration is "`Keystone to
-Keystone`_", where two keystones are linked with one acting as the identity
-source.
+and authentication method. The second type of configuration is
+":ref:`Keystone to Keystone <keystone_as_idp>`", where two keystones
+are linked with one acting as the identity source.
 
 This document discusses identity federation involving a secondary identity
 management that acts as the source of truth concerning the users it contains,
 specifically covering the SAML2.0 and OpenID Connect protocols, although
-keystone can work with other protocols. A similar concept is `external
-authentication`_ whereby keystone is still the source of truth about its users
+keystone can work with other protocols. A similar concept is :doc:`external
+authentication </admin/external-authentication>` whereby keystone is
+still the source of truth about its users
 but authentication is handled externally. Yet another closely related topic is
-`tokenless authentication`_ which uses some of the same constructs as described
+:doc:`tokenless authentication </admin/configure_tokenless_x509>`
+which uses some of the same constructs as described
 here but allows services to validate users without using keystone tokens.
 
-.. _LDAP as an identity backend: ../../admin/identity-integrate-with-ldap.html
-.. _keystone as a Service Provider (SP): configure_federation.html#keystone-as-a-service-provider-sp
-.. _Keystone to Keystone: configure_federation.html#keystone-as-an-identity-provider-idp
-.. _external authentication: ../external-authentication.html
-.. _tokenless authentication: ../configure_tokenless_x509.html
 
 --------
 Glossary
diff --git a/doc/source/admin/federation/mellon.rst b/doc/source/admin/federation/mellon.inc
index edc46991e..c278bf9b5 100644
--- a/doc/source/admin/federation/mellon.rst
+++ b/doc/source/admin/federation/mellon.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 ..
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
@@ -11,6 +13,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _mellon:
+
 -----------------
 Setting Up Mellon
 -----------------
@@ -143,6 +147,4 @@ Remember to reload Apache after finishing configuring Mellon:
 Continue configuring keystone
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`Continue configuring keystone`_
-
-.. _Continue configuring keystone: configure_federation.html#configuring-keystone
+:ref:`Continue configuring keystone <federation_configuring_keystone>`
diff --git a/doc/source/admin/federation/openidc.rst b/doc/source/admin/federation/openidc.inc
index c4d0186cf..f6c479447 100644
--- a/doc/source/admin/federation/openidc.rst
+++ b/doc/source/admin/federation/openidc.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 ..
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
@@ -11,6 +13,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _federation_openidc:
+
 -------------------------
 Setting Up OpenID Connect
 -------------------------
@@ -109,16 +113,12 @@ Remember to reload Apache after altering the VirtualHost:
 
 .. note::
 
-   When creating `mapping rules`_, in keystone, note that the 'remote'
+   When creating :ref:`mapping rules <create_a_mapping>`, in keystone, note that the 'remote'
    attributes will be prefixed, with ``HTTP_``, so for instance, if you set
    ``OIDCClaimPrefix`` to ``OIDC-``, then a typical remote value to check for
    is: ``HTTP_OIDC_ISS``.
 
-.. _`mapping rules`: configure_federation.html#mapping
-
 Continue configuring keystone
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`Continue configuring keystone`_
-
-.. _Continue configuring keystone: configure_federation.html#configuring-keystone
+:ref:`Continue configuring keystone <federation_configuring_keystone>`
diff --git a/doc/source/admin/federation/shibboleth.rst b/doc/source/admin/federation/shibboleth.inc
index 96e1a729f..9415659ad 100644
--- a/doc/source/admin/federation/shibboleth.rst
+++ b/doc/source/admin/federation/shibboleth.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 ..
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
@@ -11,6 +13,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _shibboleth:
+
 ---------------------
 Setting up Shibboleth
 ---------------------
@@ -268,6 +272,4 @@ is your Identity Provider you do not need to upload this file.
 Continue configuring keystone
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`Continue configuring keystone`_
-
-.. _Continue configuring keystone: configure_federation.html#configuring-keystone
+:ref:`Continue configuring keystone <federation_configuring_keystone>`
diff --git a/doc/source/admin/identity-concepts.rst b/doc/source/admin/identity-concepts.rst
index d322d3a02..3d615c0da 100644
--- a/doc/source/admin/identity-concepts.rst
+++ b/doc/source/admin/identity-concepts.rst
@@ -297,8 +297,7 @@ service, such as, a user named ``nova`` for the Compute service, and a
 special service project called ``service``.
 
 For information about how to create services and endpoints, see the
-`OpenStack Administrator Guide <https://docs.openstack.org/keystone/latest/
-admin/manage-services.html>`__.
+:ref:`Administrator Guide <manage_services>`.
 
 Groups
 ~~~~~~
diff --git a/doc/source/admin/identity-sources.rst b/doc/source/admin/identity-sources.rst
index 16305a332..e19e775c2 100644
--- a/doc/source/admin/identity-sources.rst
+++ b/doc/source/admin/identity-sources.rst
@@ -26,11 +26,10 @@ keystone is deciding how you want keystone to source your identity data.
 Keystone supports several different choices that will substantially impact how
 you'll configure, deploy, and interact with keystone.
 
-You can also mix-and-match various sources of identity (see `Domain-specific
-Configuration`_ for an example). For example, you can store OpenStack service users
+You can also mix-and-match various sources of identity (see
+:ref:`Domain-specific Configuration <domain_specific_configuration>` for an
+example). For example, you can store OpenStack service users
 and their passwords in SQL, manage customers in LDAP, and authenticate employees
 via SAML federation.
 
-.. _Domain-specific Configuration: domain-specific-config.html
 .. support_matrix:: identity-support-matrix.ini
-
diff --git a/doc/source/admin/integrate-with-ldap.rst b/doc/source/admin/integrate-with-ldap.inc
index 029af8e31..dbaf08bf3 100644
--- a/doc/source/admin/integrate-with-ldap.rst
+++ b/doc/source/admin/integrate-with-ldap.inc
@@ -1,3 +1,7 @@
+.. -*- rst -*-
+
+.. _integrate_with_ldap:
+
 Integrate Identity with LDAP
 ============================
 
diff --git a/doc/source/admin/limit-list-size.rst b/doc/source/admin/limit-list-size.inc
index 2de2dfd6b..f0bed1ec2 100644
--- a/doc/source/admin/limit-list-size.rst
+++ b/doc/source/admin/limit-list-size.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 ..
       Copyright 2018 SUSE Linux GmbH
       All Rights Reserved.
diff --git a/doc/source/admin/logging.rst b/doc/source/admin/logging.inc
index 901e9ac91..abd6672e2 100644
--- a/doc/source/admin/logging.rst
+++ b/doc/source/admin/logging.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 Logging
 =======
 
diff --git a/doc/source/admin/manage-services.rst b/doc/source/admin/manage-services.rst
index 5e6aaf712..914761af8 100644
--- a/doc/source/admin/manage-services.rst
+++ b/doc/source/admin/manage-services.rst
@@ -1,3 +1,5 @@
+.. _manage_services:
+
 ============================================
 Create and manage services and service users
 ============================================
diff --git a/doc/source/admin/manage-trusts.rst b/doc/source/admin/manage-trusts.rst
index 03337e3ea..e5272b0ab 100644
--- a/doc/source/admin/manage-trusts.rst
+++ b/doc/source/admin/manage-trusts.rst
@@ -3,10 +3,9 @@ Managing trusts
 ===============
 
 A trust is an OpenStack Identity extension that enables delegation and,
-optionally, impersonation through ``keystone``. See the `user guide on using
-trusts`_.
+optionally, impersonation through ``keystone``. See the :doc:`user
+guide on using trusts </user/trusts>`.
 
-.. _user guide on using trusts: ../user/trusts.html
 
 Removing Expired Trusts
 ===========================================================
diff --git a/doc/source/admin/performance.rst b/doc/source/admin/performance.inc
index 0a4532c9b..1e8a398db 100644
--- a/doc/source/admin/performance.rst
+++ b/doc/source/admin/performance.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 ..
       Licensed under the Apache License, Version 2.0 (the "License"); you may
       not use this file except in compliance with the License. You may obtain
diff --git a/doc/source/admin/resource-options.rst b/doc/source/admin/resource-options.rst
index c79aa1943..ad7ccadd5 100644
--- a/doc/source/admin/resource-options.rst
+++ b/doc/source/admin/resource-options.rst
@@ -64,8 +64,8 @@ when they start using the deployment.
        }
    }
 
-See the `security compliance documentation
-<security-compliance.html>`_ for more details.
+See the :ref:`security compliance documentation
+<security_compliance>` for more details.
 
 .. _ignore_password_expiry:
 
@@ -89,8 +89,8 @@ expired according to global configuration values.
        }
    }
 
-See the `security compliance documentation
-<security-compliance.html>`_ for more details.
+See the :ref:`security compliance documentation
+<security_compliance>` for more details.
 
 .. _ignore_lockout_failure_attempts:
 
@@ -112,8 +112,8 @@ locking out the user as a result.
        }
    }
 
-See the `security compliance documentation
-<security-compliance.html>`_ for more details.
+See the :ref:`security compliance documentation
+<security_compliance>` for more details.
 
 .. _lock_password:
 
@@ -136,8 +136,8 @@ password through self-service APIs.
    }
 
 
-See the `security compliance documentation
-<security-compliance.html>`_ for more details.
+See the :ref:`security compliance documentation
+<security_compliance>` for more details.
 
 .. _multi_factor_auth_enabled:
 
diff --git a/doc/source/admin/security-compliance.rst b/doc/source/admin/security-compliance.inc
index 5246bb51f..06700fe56 100644
--- a/doc/source/admin/security-compliance.rst
+++ b/doc/source/admin/security-compliance.inc
@@ -1,3 +1,7 @@
+.. -*- rst -*-
+
+.. _security_compliance:
+
 Security compliance and PCI-DSS
 ===============================
 
diff --git a/doc/source/admin/tokens-overview.rst b/doc/source/admin/tokens-overview.rst
index 8766be00b..ec7f022dc 100644
--- a/doc/source/admin/tokens-overview.rst
+++ b/doc/source/admin/tokens-overview.rst
@@ -6,6 +6,8 @@ Tokens are used to authenticate and authorize your interactions with the
 various OpenStack APIs. Tokens come in many scopes, representing various
 authorization and sources of identity.
 
+.. _authorization_scopes:
+
 Authorization scopes
 --------------------
 
diff --git a/doc/source/admin/troubleshoot.rst b/doc/source/admin/troubleshoot.inc
index 58d9f9386..f0cbd915c 100644
--- a/doc/source/admin/troubleshoot.rst
+++ b/doc/source/admin/troubleshoot.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 Troubleshoot the Identity service
 =================================
 
diff --git a/doc/source/admin/url-safe-naming.rst b/doc/source/admin/url-safe-naming.inc
index 4c02e435e..92be211f4 100644
--- a/doc/source/admin/url-safe-naming.rst
+++ b/doc/source/admin/url-safe-naming.inc
@@ -1,3 +1,5 @@
+.. -*- rst -*-
+
 URL safe naming of projects and domains
 =======================================
 
diff --git a/doc/source/configuration/config-options.rst b/doc/source/configuration/config-options.rst
index 895997839..e851e3982 100644
--- a/doc/source/configuration/config-options.rst
+++ b/doc/source/configuration/config-options.rst
@@ -20,8 +20,5 @@ Domain-specific Identity drivers
 The Identity service supports domain-specific Identity drivers
 installed on an SQL or LDAP back end, and supports domain-specific
 Identity configuration options, which are stored in domain-specific
-configuration files. See the
-`Admin guide Identity Management Chapter
-<https://docs.openstack.org
-/keystone/latest/admin/identity-domain-specific-config.html>`_
+configuration files. See :ref:`domain_specific_configuration`
 for more information.
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 02afdecde..5bd6d917f 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,3 +1,5 @@
+.. _keystone_configuration_options:
+
 ==============================
 Keystone Configuration Options
 ==============================
diff --git a/doc/source/contributor/auth-plugins.rst b/doc/source/contributor/auth-plugins.rst
index 055914f8e..19d118177 100644
--- a/doc/source/contributor/auth-plugins.rst
+++ b/doc/source/contributor/auth-plugins.rst
@@ -14,6 +14,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _auth_plugins:
+
 Authentication Plugins
 ======================
 
diff --git a/doc/source/contributor/developing-drivers.rst b/doc/source/contributor/developing-drivers.rst
index dff2b5d70..7f3f02fa7 100644
--- a/doc/source/contributor/developing-drivers.rst
+++ b/doc/source/contributor/developing-drivers.rst
@@ -11,6 +11,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _developing_drivers:
+
 ===========================
 Developing Keystone Drivers
 ===========================
diff --git a/doc/source/contributor/how-can-i-help.rst b/doc/source/contributor/how-can-i-help.rst
index 72378657d..6ac5b7a4a 100644
--- a/doc/source/contributor/how-can-i-help.rst
+++ b/doc/source/contributor/how-can-i-help.rst
@@ -44,7 +44,7 @@ while you learn the ropes:
 * Review `new changes`_. Keep OpenStack's `review guidelines`_ in mind. Ask
   questions when you don't understand a change.
 
-Need any help? `Reach out`_ to the keystone team.
+Need any help? :doc:`Reach out </getting-started/community>` to the keystone team.
 
 .. _keystone: https://bugs.launchpad.net/keystone/+bugs?field.tag=low-hanging-fruit
 .. _keystonemiddleware: https://bugs.launchpad.net/keystonemiddleware/+bugs?field.tag=low-hanging-fruit
@@ -54,4 +54,3 @@ Need any help? `Reach out`_ to the keystone team.
 .. _keystone maintainers: https://review.openstack.org/#/admin/groups/9,members
 .. _new changes: https://review.openstack.org/#/q/is:open+project:openstack/keystone+OR+project:openstack/keystonemiddleware+OR+project:openstack/keystoneauth+OR+project:openstack/python-keystoneclient
 .. _review guidelines: https://docs.openstack.org/project-team-guide/review-the-openstack-way.html
-.. _Reach out: ../getting-started/community.html
diff --git a/doc/source/contributor/proposing-features.rst b/doc/source/contributor/proposing-features.rst
index af383d517..81e6cc3e0 100644
--- a/doc/source/contributor/proposing-features.rst
+++ b/doc/source/contributor/proposing-features.rst
@@ -11,6 +11,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _proposing_features:
+
 ==================
 Proposing Features
 ==================
diff --git a/doc/source/contributor/services.rst b/doc/source/contributor/services.rst
index abf0e5b56..3c68972bb 100644
--- a/doc/source/contributor/services.rst
+++ b/doc/source/contributor/services.rst
@@ -499,8 +499,8 @@ you've made to policy enforcement in your service. Release notes are an
 excellent way to signal changes to operators. You can find examples when
 keystone implemented support for default roles. Additionally, you might have
 operators or users ask questions about the various scopes or what they mean.
-Don't hesitate to refer them to keystone's `scope documentation
-<https://docs.openstack.org/keystone/latest/admin/tokens-overview.html#authorization-scopes>`_.
+Don't hesitate to refer them to keystone's :ref:`scope documentation
+<authorization_scopes>`.
 
 Auth Token middleware
 =====================
diff --git a/doc/source/install/keystone-install-obs.rst b/doc/source/install/keystone-install-obs.rst
index a2baa1d4c..e99181301 100644
--- a/doc/source/install/keystone-install-obs.rst
+++ b/doc/source/install/keystone-install-obs.rst
@@ -151,6 +151,8 @@ Install and configure components
 
    Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
 
+.. _suse_configure_apache:
+
 Configure the Apache HTTP server
 --------------------------------
 
diff --git a/doc/source/install/keystone-install-rdo.rst b/doc/source/install/keystone-install-rdo.rst
index a477cfd08..f37203e9d 100644
--- a/doc/source/install/keystone-install-rdo.rst
+++ b/doc/source/install/keystone-install-rdo.rst
@@ -140,6 +140,8 @@ Install and configure components
 
    Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
 
+.. _redhat_configure_apache:
+
 Configure the Apache HTTP server
 --------------------------------
 
diff --git a/doc/source/install/keystone-install-ubuntu.rst b/doc/source/install/keystone-install-ubuntu.rst
index 92744e29e..d5ddcd0fb 100644
--- a/doc/source/install/keystone-install-ubuntu.rst
+++ b/doc/source/install/keystone-install-ubuntu.rst
@@ -144,6 +144,8 @@ Install and configure components
 
    Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
 
+.. _ubuntu_configure_apache:
+
 Configure the Apache HTTP server
 --------------------------------
 
diff --git a/doc/source/user/application_credentials.rst b/doc/source/user/application_credentials.rst
index 9c2b71c2c..f43365a1d 100644
--- a/doc/source/user/application_credentials.rst
+++ b/doc/source/user/application_credentials.rst
@@ -14,6 +14,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _application_credentials:
+
 =======================
 Application Credentials
 =======================
diff --git a/doc/source/user/trusts.rst b/doc/source/user/trusts.rst
index 69fefd338..06893e1df 100644
--- a/doc/source/user/trusts.rst
+++ b/doc/source/user/trusts.rst
@@ -73,7 +73,6 @@ The delegation parameters are:
 
 .. note::
 
-   See the administrator guide on `removing expired trusts`_ for recommended
+   See the administrator guide on :doc:`removing expired trusts
+   </admin/manage-trusts>` for recommended
    maintenance procedures.
-
-.. _`removing expired trusts`: ../admin/manage-trusts.html
diff --git a/tox.ini b/tox.ini
index 08d0348ff..9acdc699f 100644
--- a/tox.ini
+++ b/tox.ini
@@ -134,7 +134,7 @@ deps =
 commands=
     bash -c "rm -rf doc/build"
     bash -c "rm -rf doc/source/api"
-    sphinx-build -W -b html doc/source doc/build/html
+    sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
 
 [testenv:releasenotes]
 basepython = python3