Merge "doc: Start using openstackdoctheme's extlink extension"

56 files changed, 216 insertions, 213 deletions

diff --git a/api-guide/source/conf.py b/api-guide/source/conf.py
index 89edac73ea..6b0411a3d4 100644
--- a/api-guide/source/conf.py
+++ b/api-guide/source/conf.py
@@ -277,3 +277,9 @@ pdf_documents = [
     ('index', u'ComputeAPIGuide', u'Compute API Guide', u'OpenStack '
     'contributors')
 ]
+
+# -- Options for openstackdocstheme -------------------------------------------
+
+openstack_projects = [
+    'nova',
+]
diff --git a/api-guide/source/general_info.rst b/api-guide/source/general_info.rst
index fcf0218f44..df1ad5d081 100644
--- a/api-guide/source/general_info.rst
+++ b/api-guide/source/general_info.rst
@@ -247,8 +247,7 @@ on compute hosts rather than servers.
 
 -  **Aggregates**
 
-   See `Aggregates developer information
-   <https://docs.openstack.org/nova/latest/user/aggregates.html>`_.
+   See :nova-doc:`Aggregates Developer Information <user/aggregates.html>`.
 
 -  **Migrations**
 
diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst
index efa104b76f..320711592e 100644
--- a/api-guide/source/server_concepts.rst
+++ b/api-guide/source/server_concepts.rst
@@ -90,7 +90,7 @@ are exposed to administrators:
   there is no ongoing compute API calls (running tasks), vm_state should reflect
   what the customer expect the VM to be. When combined with task states,
   a better picture can be formed regarding the server's health and progress.
-  Please see: `VM States <https://docs.openstack.org/nova/latest/reference/vm-states.html>`_.
+  Refer to :nova-doc:`VM States <reference/vm-states.html>`.
 
 - task_state represents what is happening to the instance at the
   current moment. These tasks can be generic, such as 'spawning', or specific,
@@ -613,17 +613,15 @@ TODO: Add description about how to custom scheduling policy for server booting.
 Server Consoles
 ~~~~~~~~~~~~~~~
 
-Server Consoles can also be supplied after server launched.
-There are several server console services available.
-First, users can get the console output from the specified server
-and can limit the lines of console text by setting the length.
-Second, users can access multiple types of remote consoles.
-The user can use novnc, xvpvnc, rdp-html5, spice-html5, serial,
-and webmks(start from microversion 2.8) through either the OpenStack
-dashboard or the command line. Please see `Configure remote console access
-<https://docs.openstack.org/nova/latest/admin/remote-console-access.html>`_.
-Specifically for Xenserver, it provides the ability to create,
-delete, detail, list specified server vnc consoles.
+Server Consoles can also be supplied after server launched. There are several
+server console services available. First, users can get the console output
+from the specified server and can limit the lines of console text by setting
+the length. Second, users can access multiple types of remote consoles. The
+user can use novnc, xvpvnc, rdp-html5, spice-html5, serial, and webmks(start
+from microversion 2.8) through either the OpenStack dashboard or the command
+line. Refer to :nova-doc:`Configure remote console access
+<admin/remote-console-access.html>`.  Specifically for Xenserver, it provides
+the ability to create, delete, detail, list specified server vnc consoles.
 
 Server networks
 ~~~~~~~~~~~~~~~
@@ -884,8 +882,8 @@ Metadata API
 ------------
 Nova provides a metadata api for servers to retrieve server specific metadata.
 Neutron ensures this metadata api can be accessed through a predefined ip
-address (169.254.169.254). For more details, see
-`Metadata Service <https://docs.openstack.org/nova/latest/user/metadata-service.html>`_.
+address (169.254.169.254). For more details, see :nova-doc:`Metadata Service
+<user/metadata-service.html>`.
 
 Config Drive
 ------------
@@ -893,8 +891,8 @@ Config Drive
 Nova is able to write metadata to a special configuration drive that attaches
 to the server when it boots. The server can mount this drive and read files
 from it to get information that is normally available through the metadata
-service. For more details, see
-`Config Drive <https://docs.openstack.org/nova/latest/user/config-drive.html>`_.
+service. For more details, see :nova-doc:`Config Drive
+<user/config-drive.html>`.
 
 User data
 ---------
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 77fc36caec..a6bb0d5873 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -5,7 +5,7 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 sphinxcontrib-actdiag>=0.8.5 # BSD
 sphinxcontrib-seqdiag>=0.8.4 # BSD
 os-api-ref>=1.4.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
+openstackdocstheme>=1.19.0 # Apache-2.0
 
 # releasenotes
 reno>=2.5.0 # Apache-2.0
diff --git a/doc/source/admin/arch.rst b/doc/source/admin/arch.rst
index 558b7c9094..c7fe4d28b3 100644
--- a/doc/source/admin/arch.rst
+++ b/doc/source/admin/arch.rst
@@ -49,7 +49,7 @@ support across different hypervisors, see :doc:`/user/support-matrix`.
 You can also orchestrate clouds using multiple hypervisors in different
 availability zones. Compute supports the following hypervisors:
 
-- `Baremetal <https://docs.openstack.org/ironic/latest/>`__
+- :ironic-doc:`Baremetal <>`
 
 - `Docker <https://www.docker.io>`__
 
@@ -173,9 +173,8 @@ virtualization system. It is still possible for the resulting instance to keep
 ephemeral storage, depending on the flavor selected. In this case, the root
 file system can be on the persistent volume, and its state is maintained, even
 if the instance is shut down. For more information about this type of
-configuration, see `Introduction to the Block Storage service
-<https://docs.openstack.org/cinder/latest/configuration/block-storage/block-storage-overview.html>`_
-in the OpenStack Configuration Reference.
+configuration, see :cinder-doc:`Introduction to the Block Storage service
+<configuration/block-storage/block-storage-overview.html>`.
 
 .. note::
 
diff --git a/doc/source/admin/configuration/hypervisor-xen-api.rst b/doc/source/admin/configuration/hypervisor-xen-api.rst
index a5aff33545..7f9544964c 100644
--- a/doc/source/admin/configuration/hypervisor-xen-api.rst
+++ b/doc/source/admin/configuration/hypervisor-xen-api.rst
@@ -376,11 +376,10 @@ Networking configuration
 ------------------------
 
 The Networking service in the Compute node is running
-``neutron-openvswitch-agent``, this manages dom0's OVS. You can refer
-Networking `openvswitch_agent.ini sample`__ for details,
-however there are several specific items to look out for.
-
-__ https://docs.openstack.org/neutron/latest/configuration/samples/openvswitch-agent.html
+``neutron-openvswitch-agent``. This manages ``dom0``\'s OVS. You should refer
+to the :neutron-doc:`openvswitch_agent.ini sample
+<configuration/samples/openvswitch-agent.html>` for details, however there are
+several specific items to look out for.
 
 .. code-block:: ini
 
diff --git a/doc/source/admin/configuration/resize.rst b/doc/source/admin/configuration/resize.rst
index fd787af649..afe6be5217 100644
--- a/doc/source/admin/configuration/resize.rst
+++ b/doc/source/admin/configuration/resize.rst
@@ -14,9 +14,9 @@ compute nodes over ssh. For KVM you need hostnames to resolve properly and
 passwordless ssh access between your compute hosts. Direct access from one
 compute host to another is needed to copy the VM file across.
 
-Cloud end users can find out how to resize a server by reading the `OpenStack
-End User Guide <https://docs.openstack.org/user-guide/
-cli_change_the_size_of_your_server.html>`_.
+Cloud end users can find out how to resize a server by reading the
+:python-openstackclient-doc:`OpenStack CLI Guide
+<cli/command-objects/server.html#server-resize>`
 
 XenServer
 ~~~~~~~~~
diff --git a/doc/source/admin/huge-pages.rst b/doc/source/admin/huge-pages.rst
index 4e92ad7fbc..9a65e4448f 100644
--- a/doc/source/admin/huge-pages.rst
+++ b/doc/source/admin/huge-pages.rst
@@ -200,8 +200,8 @@ run:
 
    $ openstack flavor set m1.large --property hw:mem_page_size=any
 
-For more information about the syntax for ``hw:mem_page_size``, refer to the
-`Flavors`_ guide.
+For more information about the syntax for ``hw:mem_page_size``, refer to
+:doc:`flavors`.
 
 Applications are frequently packaged as images. For applications that require
 the IO performance improvements that huge pages provides, configure image
@@ -235,5 +235,4 @@ guide.
 .. Links
 .. _`Linux THP guide`: https://www.kernel.org/doc/Documentation/vm/transhuge.txt
 .. _`Linux hugetlbfs guide`: https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt
-.. _`Flavors`: https://docs.openstack.org/admin-guide/compute-flavors.html
 .. _`Image metadata`: https://docs.openstack.org/image-guide/image-metadata.html
diff --git a/doc/source/admin/manage-logs.rst b/doc/source/admin/manage-logs.rst
index 19f8f7128f..f60a523852 100644
--- a/doc/source/admin/manage-logs.rst
+++ b/doc/source/admin/manage-logs.rst
@@ -35,8 +35,8 @@ For more about the logging configuration syntax, including the ``handlers`` and
 on logging configuration files.
 
 For an example of the ``logging.conf`` file with various defined handlers, see
-the `Example Configuration File for nova
-<https://docs.openstack.org/oslo.log/latest/admin/example_nova.html>`__.
+the :oslo.log-doc:`Example Configuration File for nova
+<admin/example_nova.html>`.
 
 Syslog
 ~~~~~~
diff --git a/doc/source/admin/manage-the-cloud.rst b/doc/source/admin/manage-the-cloud.rst
index fe581b8664..33cc911a8b 100644
--- a/doc/source/admin/manage-the-cloud.rst
+++ b/doc/source/admin/manage-the-cloud.rst
@@ -21,9 +21,8 @@ might be restricted by the Identity service.
    variables for convenience), for the ability to administer the cloud from the
    command line.
 
-   To install python-openstackclient, follow the instructions in the `OpenStack
-   User Guide
-   <https://docs.openstack.org/user-guide/common/cli-install-openstack-command-line-clients.html>`_.
+   For more information on ``python-openstackclient``, refer to the
+   :python-openstackclient-doc:`documentation <>`.
 
 #. Confirm the installation was successful:
 
@@ -44,9 +43,9 @@ might be restricted by the Identity service.
 
       $ openstack help SUBCOMMAND
 
-   For a complete list of ``openstack`` commands and parameters, see the
-   `OpenStack Command-Line Reference
-   <https://docs.openstack.org/cli-reference/openstack.html>`__.
+   For a complete list of ``openstack`` commands and parameters, refer to the
+   :python-openstackclient-doc:`OpenStack Command-Line Reference
+   <cli/index.html>`.
 
 #. Set the required parameters as environment variables to make running
    commands easier. For example, you can add ``--os-username`` as an
diff --git a/doc/source/admin/manage-volumes.rst b/doc/source/admin/manage-volumes.rst
index ed7f12137b..1ac2a7a499 100644
--- a/doc/source/admin/manage-volumes.rst
+++ b/doc/source/admin/manage-volumes.rst
@@ -6,11 +6,11 @@ Depending on the setup of your cloud provider, they may give you an endpoint to
 use to manage volumes. You can use the ``openstack`` CLI to manage volumes.
 
 For the purposes of the compute service, attaching, detaching and
-:doc:`creating a server from a volume <../user/launch-instance-from-volume>`
-are of primary interest.
+:doc:`creating a server from a volume </user/launch-instance-from-volume>` are
+of primary interest.
 
-Refer to the `block storage service CLI guide on managing volumes
-<https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html>`_.
+Refer to the :python-openstackclient-doc:`CLI documentation
+<cli/command-objects/volume.html>` for more information.
 
 
 Volume multi-attach
@@ -19,7 +19,8 @@ Volume multi-attach
 Nova `added support for multiattach volumes`_ in the 17.0.0 Queens release.
 
 This document covers the nova-specific aspects of this feature. Refer
-to the `block storage admin guide`_ for more details about creating
+to the :cinder-doc:`block storage admin guide
+<admin/blockstorage-volume-multiattach.html>` for more details about creating
 multiattach-capable volumes.
 
 Boot from volume and attaching a volume to a server that is not
@@ -33,11 +34,12 @@ Requirements
 ~~~~~~~~~~~~
 
 * The minimum required compute API microversion for attaching a
-  multiattach-capable volume to more than one server is `2.60`_.
+  multiattach-capable volume to more than one server is :ref:`2.60
+  <api-microversion-queens>`.
 * Cinder 12.0.0 (Queens) or newer is required.
 * The ``nova-compute`` service must be running at least Queens release level
   code (17.0.0) and the hypervisor driver must support attaching block storage
-  devices to more than one guest. Refer to the `feature support matrix`_ for
+  devices to more than one guest. Refer to :doc:`/user/support-matrix` for
   details on which compute drivers support volume multiattach.
 * When using the libvirt compute driver, the following native package versions
   determine multiattach support:
@@ -72,9 +74,6 @@ volume back end. It purposefully does not use the Pike Ubuntu Cloud Archive
 package mirror so that it gets qemu<2.10.
 
 .. _added support for multiattach volumes: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/multi-attach-volume.html
-.. _block storage admin guide: https://docs.openstack.org/cinder/latest/admin/blockstorage-volume-multiattach.html
 .. _recorded overview and demo: https://www.youtube.com/watch?v=hZg6wqxdEHk
-.. _2.60: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#maximum-in-queens
-.. _feature support matrix: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_multiattach_volume
 .. _nova repository: http://git.openstack.org/cgit/openstack/nova/tree/playbooks/legacy/nova-multiattach/run.yaml
 .. _tempest repository: http://codesearch.openstack.org/?q=CONF.compute_feature_enabled.volume_multiattach&i=nope&files=&repos=tempest
diff --git a/doc/source/admin/networking-nova.rst b/doc/source/admin/networking-nova.rst
index 4e36ed7e96..d071a5cbc7 100644
--- a/doc/source/admin/networking-nova.rst
+++ b/doc/source/admin/networking-nova.rst
@@ -13,8 +13,8 @@ configuration for your Compute instances.
 
 You can choose to either install and configure ``nova-network`` or use the
 OpenStack Networking service (neutron). This section contains a brief overview
-of ``nova-network``. For more information about OpenStack Networking, see
-`Networking <https://docs.openstack.org/admin-guide/networking.html>`_.
+of ``nova-network``. For more information about OpenStack Networking, refer to
+:neutron-doc:`the documentation <>`.
 
 Networking concepts
 ~~~~~~~~~~~~~~~~~~~
@@ -417,9 +417,8 @@ Configure public (floating) IP addresses
 
 This section describes how to configure floating IP addresses with
 ``nova-network``. For information about doing this with OpenStack Networking,
-see `L3-routing-and-NAT
-<https://docs.openstack.org/neutron/latest/admin/archives/adv-features.html
-#l3-routing-and-nat>`_.
+refer to :neutron-doc:`L3-routing-and-NAT
+<admin/archives/adv-features.html#l3-routing-and-nat>`.
 
 Private and public IP addresses
 -------------------------------
@@ -561,9 +560,9 @@ perform floating IP operations:
      # openstack floating ip delete CIDR
 
 For more information about how administrators can associate floating IPs with
-instances, see `ip floating
-<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/
-ip-floating.html>`__ in the python-openstackclient User Documentation.
+instances, see :python-openstackclient-doc:`ip floating
+<cli/command-objects/ip-floating.html>` in the *python-openstackclient* User
+Documentation.
 
 Automatically add floating IPs
 ------------------------------
diff --git a/doc/source/admin/pci-passthrough.rst b/doc/source/admin/pci-passthrough.rst
index abfc99b311..f4f06e0c5d 100644
--- a/doc/source/admin/pci-passthrough.rst
+++ b/doc/source/admin/pci-passthrough.rst
@@ -18,7 +18,7 @@ assigned to only one guest and cannot be shared.
 .. note::
 
    For information on attaching virtual SR-IOV devices to guests, refer to the
-   `Networking Guide`_.
+   :neutron-doc:`Networking Guide <admin/config-sriov>`.
 
 To enable PCI passthrough, follow the steps below:
 
@@ -40,7 +40,9 @@ To enable PCI passthrough, follow the steps below:
 Configure nova-scheduler (Controller)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-#. Configure ``nova-scheduler`` as specified in `Configure nova-scheduler`_.
+#. Configure ``nova-scheduler`` as specified in :neutron-doc:`Configure
+   nova-scheduler
+   <admin/config-sriov.html#configure-nova-scheduler-controller`.
 
 #. Restart the ``nova-scheduler`` service.
 
@@ -82,7 +84,8 @@ Enable PCI passthrough (Compute)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Enable VT-d and IOMMU. For more information, refer to steps one and two in
-`Create Virtual Functions`_.
+:neutron-doc:`Create Virtual Functions
+<admin/config-sriov.html#create-virtual-functions-compute`.
 
 For Hyper-V compute nodes, the requirements are as follows:
 
@@ -100,8 +103,10 @@ devices, run the following Powershell commands:
 
 If the compute node passes all the requirements, the desired assignable PCI
 devices to be disabled and unmounted from the host, in order to be assignable
-by Hyper-V. The following can be read for more details: `Hyper-V PCI passthrough`_.
+by Hyper-V. The following can be read for more details: `Hyper-V PCI
+passthrough`__.
 
+.. __: https://blogs.technet.microsoft.com/heyscriptingguy/2016/07/14/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
 
 Configure PCI devices (Compute)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,9 +162,3 @@ available with the specified ``vendor_id`` and ``product_id`` that matches the
 .. code-block:: console
 
    # openstack server create --flavor m1.large --image cirros-0.3.5-x86_64-uec --wait test-pci
-
-.. Links
-.. _`Create Virtual Functions`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html#create-virtual-functions-compute
-.. _`Configure nova-scheduler`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html#configure-nova-scheduler-controller
-.. _`Networking Guide`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html
-.. _`Hyper-V PCI passthrough`: https://blogs.technet.microsoft.com/heyscriptingguy/2016/07/14/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
diff --git a/doc/source/admin/service-groups.rst b/doc/source/admin/service-groups.rst
index 83fee853ae..e19522d0eb 100644
--- a/doc/source/admin/service-groups.rst
+++ b/doc/source/admin/service-groups.rst
@@ -47,8 +47,7 @@ To use the memcache driver, you must install memcached. You might already have
 it installed, as the same driver is also used for the OpenStack Object Storage
 and OpenStack dashboard. To install memcached, see the *Environment ->
 Memcached* section in the `Installation Tutorials and Guides
-<https://docs.openstack.org/project-install-guide/ocata>`_ depending on your
-distribution.
+<https://docs.openstack.org/install-guide>`_ depending on your distribution.
 
 These values in the ``/etc/nova/nova.conf`` file are required on every node for
 the memcache driver:
diff --git a/doc/source/admin/virtual-gpu.rst b/doc/source/admin/virtual-gpu.rst
index b558d4b4a2..ab8e2c9e4f 100644
--- a/doc/source/admin/virtual-gpu.rst
+++ b/doc/source/admin/virtual-gpu.rst
@@ -66,9 +66,7 @@ Configure a flavor to request one virtual GPU:
 The enabled vGPU types on the compute hosts are not exposed to API users.
 Flavors configured for vGPU support can be tied to host aggregates as a means
 to properly schedule those flavors onto the compute hosts that support them.
-See the `host aggregates`_ guide for more information.
-
-.. _host aggregates: https://docs.openstack.org/nova/latest/user/aggregates.html
+See the :doc:`/user/aggregates` for more information.
 
 Create instances with virtual GPU devices
 -----------------------------------------
diff --git a/doc/source/cli/nova-api-metadata.rst b/doc/source/cli/nova-api-metadata.rst
index 5686d50473..3121280fd4 100644
--- a/doc/source/cli/nova-api-metadata.rst
+++ b/doc/source/cli/nova-api-metadata.rst
@@ -41,8 +41,8 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
-* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/wsgi.html>`__
+* :nova-doc:`OpenStack Nova <>`
+* :nova-doc:`Using WSGI with Nova <wsgi.html>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-api-os-compute.rst b/doc/source/cli/nova-api-os-compute.rst
index ac3c56b2a5..56d53eed20 100644
--- a/doc/source/cli/nova-api-os-compute.rst
+++ b/doc/source/cli/nova-api-os-compute.rst
@@ -41,8 +41,8 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
-* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/user/wsgi.html>`__
+* :nova-doc:`OpenStack Nova <>`
+* :nova-doc:`Using WSGI with Nova <user/wsgi.html>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-api.rst b/doc/source/cli/nova-api.rst
index bbc36c865b..ea58d671a0 100644
--- a/doc/source/cli/nova-api.rst
+++ b/doc/source/cli/nova-api.rst
@@ -41,8 +41,8 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
-* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/user/wsgi.html>`__
+* :nova-doc:`OpenStack Nova <>`
+* :nova-doc:`Using WSGI with Nova <user/wsgi.html>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-cells.rst b/doc/source/cli/nova-cells.rst
index 8c10750df4..90b6639384 100644
--- a/doc/source/cli/nova-cells.rst
+++ b/doc/source/cli/nova-cells.rst
@@ -46,7 +46,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-compute.rst b/doc/source/cli/nova-compute.rst
index 1ecc0fe536..f48478e8be 100644
--- a/doc/source/cli/nova-compute.rst
+++ b/doc/source/cli/nova-compute.rst
@@ -42,7 +42,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-conductor.rst b/doc/source/cli/nova-conductor.rst
index 8028379d1e..cfa5380645 100644
--- a/doc/source/cli/nova-conductor.rst
+++ b/doc/source/cli/nova-conductor.rst
@@ -37,7 +37,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-console.rst b/doc/source/cli/nova-console.rst
index ebe2758ad5..1d3eb4e186 100644
--- a/doc/source/cli/nova-console.rst
+++ b/doc/source/cli/nova-console.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-consoleauth.rst b/doc/source/cli/nova-consoleauth.rst
index e7c8a71cbe..32e037ae59 100644
--- a/doc/source/cli/nova-consoleauth.rst
+++ b/doc/source/cli/nova-consoleauth.rst
@@ -45,7 +45,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-dhcpbridge.rst b/doc/source/cli/nova-dhcpbridge.rst
index c3b77ca248..9fe5b143b8 100644
--- a/doc/source/cli/nova-dhcpbridge.rst
+++ b/doc/source/cli/nova-dhcpbridge.rst
@@ -48,7 +48,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-manage.rst b/doc/source/cli/nova-manage.rst
index 8a6dbb2598..52794d8552 100644
--- a/doc/source/cli/nova-manage.rst
+++ b/doc/source/cli/nova-manage.rst
@@ -279,7 +279,7 @@ Nova Cells v2
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-network.rst b/doc/source/cli/nova-network.rst
index d8d1ad56a5..75234e35f0 100644
--- a/doc/source/cli/nova-network.rst
+++ b/doc/source/cli/nova-network.rst
@@ -45,7 +45,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-novncproxy.rst b/doc/source/cli/nova-novncproxy.rst
index 16810dd6af..2811474e35 100644
--- a/doc/source/cli/nova-novncproxy.rst
+++ b/doc/source/cli/nova-novncproxy.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-rootwrap.rst b/doc/source/cli/nova-rootwrap.rst
index 3f1410bff7..bb2d85f6f2 100644
--- a/doc/source/cli/nova-rootwrap.rst
+++ b/doc/source/cli/nova-rootwrap.rst
@@ -57,7 +57,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-scheduler.rst b/doc/source/cli/nova-scheduler.rst
index 99b29207ea..30d31c265c 100644
--- a/doc/source/cli/nova-scheduler.rst
+++ b/doc/source/cli/nova-scheduler.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-serialproxy.rst b/doc/source/cli/nova-serialproxy.rst
index d05fa6e68f..cae809b1a2 100644
--- a/doc/source/cli/nova-serialproxy.rst
+++ b/doc/source/cli/nova-serialproxy.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-spicehtml5proxy.rst b/doc/source/cli/nova-spicehtml5proxy.rst
index 892ae3c463..bb98904ff6 100644
--- a/doc/source/cli/nova-spicehtml5proxy.rst
+++ b/doc/source/cli/nova-spicehtml5proxy.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-status.rst b/doc/source/cli/nova-status.rst
index 80cf68077a..de2571698c 100644
--- a/doc/source/cli/nova-status.rst
+++ b/doc/source/cli/nova-status.rst
@@ -93,7 +93,7 @@ Upgrade
     make a successful request to the endpoint. The command also checks to
     see that there are compute node resource providers checking in with the
     Placement service. More information on the Placement service can be found
-    at: `<https://docs.openstack.org/nova/latest/user/placement.html>`_
+    at :nova-doc:`user/placement.html>`.
 
   **16.0.0 (Pike)**
 
@@ -117,7 +117,7 @@ Upgrade
 See Also
 ========
 
-* OpenStack Nova Docs: `<https://docs.openstack.org/nova/latest/>`_
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/cli/nova-xvpvncproxy.rst b/doc/source/cli/nova-xvpvncproxy.rst
index 0afdd5bc16..5b02e314c5 100644
--- a/doc/source/cli/nova-xvpvncproxy.rst
+++ b/doc/source/cli/nova-xvpvncproxy.rst
@@ -41,7 +41,7 @@ Files
 See Also
 ========
 
-* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
+* :nova-doc:`OpenStack Nova <>`
 
 Bugs
 ====
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 61d4850405..b163e8d729 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -171,6 +171,27 @@ latex_documents = [
      u'OpenStack Foundation', 'manual'),
 ]
 
+# -- Options for openstackdocstheme -------------------------------------------
+
+# keep this ordered to keep mriedem happy
+openstack_projects = [
+    'ceilometer',
+    'cinder',
+    'glance',
+    'horizon',
+    'ironic',
+    'keystone',
+    'neutron',
+    'nova',
+    'oslo.log',
+    'oslo.messaging',
+    'oslo.i18n',
+    'oslo.versionedobjects',
+    'python-novaclient',
+    'python-openstackclient',
+    'reno',
+    'watcher',
+]
 # -- Custom extensions --------------------------------------------------------
 
 
diff --git a/doc/source/contributor/how-to-get-involved.rst b/doc/source/contributor/how-to-get-involved.rst
index af9fbe85e4..960fae37ad 100644
--- a/doc/source/contributor/how-to-get-involved.rst
+++ b/doc/source/contributor/how-to-get-involved.rst
@@ -328,7 +328,7 @@ How to do great nova-spec reviews?
 
 https://specs.openstack.org/openstack/nova-specs/specs/rocky/template.html
 
-https://docs.openstack.org/nova/latest/contributor/blueprints.html#specs
+:doc:`/contributor/blueprints`.
 
 Spec reviews are always a step ahead of the normal code reviews. Follow
 the above links for some great information on specs/reviews.
diff --git a/doc/source/contributor/microversions.rst b/doc/source/contributor/microversions.rst
index 74a61c9766..e984bbfcc9 100644
--- a/doc/source/contributor/microversions.rst
+++ b/doc/source/contributor/microversions.rst
@@ -356,8 +356,8 @@ necessary to add changes to other places which describe your change:
 * Add a verbose description to
   ``nova/api/openstack/compute/rest_api_version_history.rst``.
 
-* Add a `release note`_ with a ``features`` section announcing the new or
-  changed feature and the microversion.
+* Add a :doc:`release note </contributor/releasenotes>` with a ``features``
+  section announcing the new or changed feature and the microversion.
 
 * Update the expected versions in affected tests, for example in
   ``nova/tests/unit/api/openstack/compute/test_versions.py``.
@@ -375,7 +375,6 @@ necessary to add changes to other places which describe your change:
 * Update the `API Reference`_ documentation as appropriate.  The source is
   located under `api-ref/source/`.
 
-.. _release note: https://docs.openstack.org/nova/latest/contributor/releasenotes.html
 .. _API Reference: https://developer.openstack.org/api-ref/compute/
 
 Allocating a microversion
diff --git a/doc/source/contributor/placement.rst b/doc/source/contributor/placement.rst
index 12773d1ddc..faa2820484 100644
--- a/doc/source/contributor/placement.rst
+++ b/doc/source/contributor/placement.rst
@@ -40,10 +40,11 @@ increasing the number of WSGI application instances and scaling the RDBMS using
 traditional database scaling techniques.
 
 For sake of consistency and because there was initially intent to make the
-entities in the placement service available over RPC, `versioned objects`_ are
-used to provide the interface between the HTTP application layer and the
-SQLAlchemy-driven persistence layer. Even without RPC, these objects provide
-useful structuring and separation of the code.
+entities in the placement service available over RPC,
+:oslo.versionedobjects-doc:`versioned objects <>` are used to provide the
+interface between the HTTP application layer and the SQLAlchemy-driven
+persistence layer. Even without RPC, these objects provide useful structuring
+and separation of the code.
 
 Though the placement service doesn't aspire to be a `microservice` it does
 aspire to continue to be small and minimally complex. This means a relatively
@@ -145,8 +146,8 @@ there are a few bits of required housekeeping that must be done in the code:
   microversion and give a very brief summary of the added feature.
 * Update ``nova/api/openstack/placement/rest_api_version_history.rst``
   to add a more detailed section describing the new microversion.
-* Add a `release note`_ with a ``features`` section announcing the new or
-  changed feature and the microversion.
+* Add a :reno-doc:`release note <>` with a ``features`` section announcing the
+  new or changed feature and the microversion.
 * If the ``version_handler`` decorator (see below) has been used,
   increment ``TOTAL_VERSIONED_METHODS`` in
   ``nova/tests/unit/api/openstack/placement/test_microversion.py``.
@@ -413,13 +414,11 @@ When creating new code for the placement service, please be aware of the plan
 for an eventual extraction and avoid creating unnecessary interdependencies.
 
 .. _WSGI: https://www.python.org/dev/peps/pep-3333/
-.. _versioned objects: http://docs.openstack.org/developer/oslo.versionedobjects/
 .. _wsgify: http://docs.webob.org/en/latest/api/dec.html
 .. _WebOb: http://docs.webob.org/en/latest/
 .. _Request: http://docs.webob.org/en/latest/reference.html#request
 .. _Response: http://docs.webob.org/en/latest/#response
 .. _microversions: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
-.. _release note: https://docs.openstack.org/reno/latest/user/usage.html
 .. _gabbi: https://gabbi.readthedocs.io/
 .. _telemetry: http://specs.openstack.org/openstack/telemetry-specs/specs/kilo/declarative-http-tests.html
 .. _wsgi-intercept: http://wsgi-intercept.readthedocs.io/
diff --git a/doc/source/contributor/policies.rst b/doc/source/contributor/policies.rst
index 8a33521059..f1f611a50d 100644
--- a/doc/source/contributor/policies.rst
+++ b/doc/source/contributor/policies.rst
@@ -108,7 +108,8 @@ Metrics Gathering
 Nova currently has a monitor plugin to gather CPU metrics on compute nodes.
 This feeds into the MetricsFilter and MetricsWeigher in the scheduler. The
 CPU metrics monitor is only implemented for the libvirt compute driver.
-External projects like `Ceilometer`_ and `Watcher`_ consume these metrics.
+External projects like :ceilometer-doc:`Ceilometer <>` and
+:watcher-doc:`Watcher <>` consume these metrics.
 
 Over time people have tried to add new monitor plugins for things like memory
 bandwidth. There have also been attempts to expose these monitors over CLI,
@@ -127,6 +128,4 @@ replacement, the deprecation is open-ended, but serves as a signal that new
 deployments should not rely on the metrics that Nova gathers and should instead
 focus their efforts on alternative solutions for placement.
 
-.. _Ceilometer: https://docs.openstack.org/ceilometer/latest/
-.. _Watcher: https://docs.openstack.org/watcher/latest/
 .. _Newton midcycle: http://lists.openstack.org/pipermail/openstack-dev/2016-August/100600.html
diff --git a/doc/source/contributor/process.rst b/doc/source/contributor/process.rst
index 0141b04216..102195eb46 100644
--- a/doc/source/contributor/process.rst
+++ b/doc/source/contributor/process.rst
@@ -223,9 +223,7 @@ when you create the bug report).
 When do I need a blueprint vs a spec?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For more details see:
-
--  https://docs.openstack.org/nova/latest/contributor/blueprints.html
+For more details refer to :doc:`/contributor/blueprints`.
 
 To understand this question, we need to understand why blueprints and
 specs are useful.
@@ -426,8 +424,7 @@ Interoperable API, supporting a vibrant ecosystem
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 An interoperable API that gives users on-demand access to compute
-resources is at the heart of Nova's mission:
-https://docs.openstack.org/nova/latest/contributor/project-scope.html#mission
+resources is at the heart of :ref:`nova's mission <nova-mission>`.
 
 Nova has a vibrant ecosystem of tools built on top of the current Nova
 API. All features should be designed to work with all technology
@@ -910,9 +907,8 @@ this technique during M.
 Feature Classification
 ~~~~~~~~~~~~~~~~~~~~~~
 
-This is a look at moving forward this effort:
-
--  https://docs.openstack.org/nova/latest/user/support-matrix.html
+This is a look at moving forward the :doc:`support matrix effort
+</user/support-matrix>`.
 
 The things we need to cover:
 
diff --git a/doc/source/contributor/project-scope.rst b/doc/source/contributor/project-scope.rst
index 6984d2afd7..327592bfd9 100644
--- a/doc/source/contributor/project-scope.rst
+++ b/doc/source/contributor/project-scope.rst
@@ -22,8 +22,10 @@ should and should not be doing, and why.
 Please treat this as a discussion of interesting, and hopefully useful,
 examples. It is not intended to be an exhaustive policy statement.
 
+.. _nova-mission:
+
 Mission
---------
+-------
 
 Our mission statement starts with:
 
diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst
index db40ad8b4a..996889f43e 100644
--- a/doc/source/contributor/releasenotes.rst
+++ b/doc/source/contributor/releasenotes.rst
@@ -6,13 +6,12 @@ Release Notes
 What is reno ?
 --------------
 
-Nova uses `reno <http://docs.openstack.org/developer/reno/usage.html>`_ for
-providing release notes in-tree. That means that a patch can include a *reno
-file* or a series can have a follow-on change containing that file explaining
-what the impact is.
+Nova uses :reno-doc:`reno <>` for providing release notes in-tree. That means
+that a patch can include a *reno file* or a series can have a follow-on change
+containing that file explaining what the impact is.
 
-A *reno file* is a YAML file written in the releasenotes/notes tree which is
-generated using the reno tool this way:
+A *reno file* is a YAML file written in the ``releasenotes/notes`` tree which
+is generated using the *reno* tool this way:
 
 .. code-block:: bash
 
@@ -21,8 +20,7 @@ generated using the reno tool this way:
 where usually ``<name-your-file>`` can be ``bp-<blueprint_name>`` for a
 blueprint or ``bug-XXXXXX`` for a bugfix.
 
-Refer to the `reno documentation <http://docs.openstack.org/developer/reno/usage.html#editing-a-release-note>`_
-for the full list of sections.
+Refer to the :reno-doc:`reno documentation <user/index.html>` for more information.
 
 
 When a release note is needed
@@ -48,8 +46,10 @@ need to provide a release note :-)
     * If the patch has an `APIImpact <http://docs.openstack.org/infra/manual/developers.html#peer-review>`_ tag
     * For nova-manage and python-novaclient changes, if it adds or changes a
       new command, including adding new options to existing commands
-    * not all blueprints in general, just the ones impacting a `contractual API <http://docs.openstack.org/developer/nova/policies.html#public-contractual-apis>`_
-    * a new virt driver is provided or an existing driver impacts the `HypervisorSupportMatrix <http://docs.openstack.org/developer/nova/support-matrix.html>`_
+    * not all blueprints in general, just the ones impacting a
+      :doc:`/contributor/policies`
+    * a new virt driver is provided or an existing driver impacts the
+      :doc:`HypervisorSupportMatrix </user/support-matrix>`
 
 * ``critical``
     * Bugfixes categorized as Critical in Launchpad *impacting users*
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fec5c4b272..86191a97b9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -30,13 +30,12 @@ servers to provide that service.
 
 It requires the following additional OpenStack services for basic function:
 
-* `Keystone <https://docs.openstack.org/keystone/latest/>`__: This provides
-  identity and authentication for all OpenStack services.
-* `Glance <https://docs.openstack.org/glance/latest/>`__: This provides the
-  compute image repository. All compute instances launch from glance images.
-* `Neutron <https://docs.openstack.org/neutron/latest/>`__: This is
-  responsible for provisioning the virtual or physical networks that compute
-  instances connect to on boot.
+* :keystone-doc:`Keystone <>`: This provides identity and authentication for
+  all OpenStack services.
+* :glance-doc:`Glance <>`: This provides the compute image repository. All
+  compute instances launch from glance images.
+* :neutron-doc:`Neutron <>`: This is responsible for provisioning the virtual
+  or physical networks that compute instances connect to on boot.
 
 It can also integrate with other services to include: persistent block
 storage, encrypted disks, and baremetal compute instances.
@@ -50,19 +49,15 @@ either tools or the API directly.
 Tools for using Nova
 --------------------
 
-* `Horizon
-  <https://docs.openstack.org/horizon/latest/user/launch-instances.html>`_: The
-  official web ui for the OpenStack Project.
-* `OpenStack Client
-  <https://docs.openstack.org/python-openstackclient/latest/>`_: The official
-  CLI for OpenStack Projects. You should use this as your CLI for most things,
-  it includes not just nova commands but also commands for most of the projects
-  in OpenStack.
-* `Nova Client
-  <https://docs.openstack.org/python-novaclient/latest/user/shell.html>`_: For
-  some very advanced features (or administrative commands) of nova you may need
-  to use nova client. It is still supported, but the ``openstack`` cli is
-  recommended.
+* :horizon-doc:`Horizon <user/launch-instances.html>`: The official web UI for
+  the OpenStack Project.
+* :python-openstackclient-doc:`OpenStack Client <>`: The official CLI for
+  OpenStack Projects. You should use this as your CLI for most things, it
+  includes not just nova commands but also commands for most of the projects in
+  OpenStack.
+* :python-novaclient-doc:`Nova Client <user/shell.html>`: For some very
+  advanced features (or administrative commands) of nova you may need to use
+  nova client. It is still supported, but the ``openstack`` cli is recommended.
 
 Writing to the API
 ------------------
@@ -117,11 +112,9 @@ Installation
 .. TODO(sdague): links to all the rest of the install guide pieces.
 
 The detailed install guide for nova. A functioning nova will also require
-having installed `keystone
-<https://docs.openstack.org/keystone/latest/install/>`__, `glance
-<https://docs.openstack.org/glance/latest/install/>`__, and `neutron
-<https://docs.openstack.org/neutron/latest/install/>`__. Please ensure that you
-follow their install guides first.
+having installed :keystone-doc:`keystone <install/>`, :glance-doc:`glance
+<install/>`, and :neutron-doc:`neutron <install/>`. Ensure that you follow
+their install guides first.
 
 .. toctree::
    :maxdepth: 2
diff --git a/doc/source/install/compute-install-obs.rst b/doc/source/install/compute-install-obs.rst
index 00ae9438cf..75fbaac070 100644
--- a/doc/source/install/compute-install-obs.rst
+++ b/doc/source/install/compute-install-obs.rst
@@ -122,10 +122,9 @@ Install and configure components
         firewall service by using the
         ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/compute-install-obs.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/compute-install-obs.html>` for more details.
 
    * In the ``[vnc]`` section, enable and configure remote console access:
 
diff --git a/doc/source/install/compute-install-rdo.rst b/doc/source/install/compute-install-rdo.rst
index c50d990f0c..867ed9ff2a 100644
--- a/doc/source/install/compute-install-rdo.rst
+++ b/doc/source/install/compute-install-rdo.rst
@@ -114,10 +114,10 @@ Install and configure components
         service by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall
         driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/compute-install-rdo.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/compute-install-rdo.html#configure-the-compute-service-to-use-the-networking-service>`
+     for more details.
 
    * In the ``[vnc]`` section, enable and configure remote console access:
 
diff --git a/doc/source/install/compute-install-ubuntu.rst b/doc/source/install/compute-install-ubuntu.rst
index dda3ec601d..a00b645935 100644
--- a/doc/source/install/compute-install-ubuntu.rst
+++ b/doc/source/install/compute-install-ubuntu.rst
@@ -104,10 +104,10 @@ Install and configure components
         service by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall
         driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/compute-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/compute-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service>`
+     for more details.
 
    * In the ``[vnc]`` section, enable and configure remote console access:
 
diff --git a/doc/source/install/controller-install-obs.rst b/doc/source/install/controller-install-obs.rst
index eabdee96c1..9ced92acc5 100644
--- a/doc/source/install/controller-install-obs.rst
+++ b/doc/source/install/controller-install-obs.rst
@@ -378,10 +378,10 @@ Install and configure components
         Compute firewall driver by using the
         ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service>`
+     for more details.
 
    * In the ``[vnc]`` section, configure the VNC proxy to use the management
      interface IP address of the controller node:
diff --git a/doc/source/install/controller-install-rdo.rst b/doc/source/install/controller-install-rdo.rst
index 15d2f51e0c..b3217ea4a7 100644
--- a/doc/source/install/controller-install-rdo.rst
+++ b/doc/source/install/controller-install-rdo.rst
@@ -369,10 +369,9 @@ Install and configure components
         Compute firewall driver by using the
         ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/controller-install-rdo.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/compute-install-rdo.html>` for more details.
 
    * In the ``[vnc]`` section, configure the VNC proxy to use the management
      interface IP address of the controller node:
diff --git a/doc/source/install/controller-install-ubuntu.rst b/doc/source/install/controller-install-ubuntu.rst
index c7a50c67cf..c97d9d8ad0 100644
--- a/doc/source/install/controller-install-ubuntu.rst
+++ b/doc/source/install/controller-install-ubuntu.rst
@@ -359,10 +359,10 @@ Install and configure components
         Compute firewall driver by using the
         ``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
 
-   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
-     `Networking service install guide`__ for more details.
-
-     .. __: https://docs.openstack.org/neutron/latest/install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service
+   * Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
+     the :neutron-doc:`Networking service install guide
+     <install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service>`
+     for more information.
 
    * In the ``[vnc]`` section, configure the VNC proxy to use the management
      interface IP address of the controller node:
diff --git a/doc/source/reference/i18n.rst b/doc/source/reference/i18n.rst
index d9435816ad..799049b91f 100644
--- a/doc/source/reference/i18n.rst
+++ b/doc/source/reference/i18n.rst
@@ -1,8 +1,7 @@
 Internationalization
 ====================
 
-Nova uses the `oslo.i18n library
-<http://docs.openstack.org/developer/oslo.i18n/index.html>`_ to support
+Nova uses the :oslo.i18n-doc:`oslo.i18n library <>` to support
 internationalization. The oslo.i18n library is built on top of `gettext
 <http://docs.python.org/library/gettext.html>`_ and provides functions that are
 used to enable user-facing strings such as log messages to appear in the
diff --git a/doc/source/reference/notifications.rst b/doc/source/reference/notifications.rst
index 113228b6a1..dda515a7ea 100644
--- a/doc/source/reference/notifications.rst
+++ b/doc/source/reference/notifications.rst
@@ -13,12 +13,13 @@
 
 Notifications in Nova
 =====================
+
 Similarly to other OpenStack services Nova emits notifications to the message
-bus with the Notifier class provided by oslo.messaging [1]_. From the
-notification consumer point of view a notification consists of two parts: an
-envelope with a fixed structure defined by oslo.messaging and a payload defined
-by the service emitting the notification. The envelope format is the
-following::
+bus with the Notifier class provided by :oslo.messaging-doc:`oslo.messaging
+<reference/notifier.html>`. From the notification consumer point of view a
+notification consists of two parts: an envelope with a fixed structure defined
+by oslo.messaging and a payload defined by the service emitting the
+notification. The envelope format is the following::
 
     {
         "priority": <string, selected from a predefined list by the sender>,
@@ -62,7 +63,7 @@ The versioned notification concept is created to fix the shortcomings of the
 unversioned notifications. The envelope structure of the emitted notification
 is the same as in the unversioned notification case as it is provided by
 oslo.messaging. However the payload is not a free form dictionary but a
-serialized oslo versionedobject [2]_.
+serialized :oslo.versionedobjects-doc:`oslo versionedobjects object <>`.
 
 .. _service.update:
 
@@ -300,9 +301,9 @@ notification should be created with care to avoid future needs of adding extra
 level of inheritance that changes the name of the leaf class as that name is
 present in the payload class. If this cannot be avoided and the only change is
 the renaming then the version of the new payload shall be the same as the old
-payload was before the rename. See [3]_ as an example. If the renaming
+payload was before the rename. See [1]_ as an example. If the renaming
 involves any other changes on the payload (e.g. adding new fields) then the
-version of the new payload shall be higher than the old payload was. See [4]_
+version of the new payload shall be higher than the old payload was. See [2]_
 as an example.
 
 What should be in the notification payload
@@ -344,9 +345,5 @@ Existing versioned notifications
 
 .. versioned_notifications::
 
-
-
-.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
-.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
-.. [3] https://review.openstack.org/#/c/463001/
-.. [4] https://review.openstack.org/#/c/453077/
+.. [1] https://review.openstack.org/#/c/463001/
+.. [2] https://review.openstack.org/#/c/453077/
diff --git a/doc/source/user/cellsv2-layout.rst b/doc/source/user/cellsv2-layout.rst
index bbf116a235..6883aafef9 100644
--- a/doc/source/user/cellsv2-layout.rst
+++ b/doc/source/user/cellsv2-layout.rst
@@ -285,10 +285,11 @@ Notifications
 
 With a multi-cell environment with multiple message queues, it is
 likely that operators will want to configure a separate connection to
-a unified queue for notifications. This can be done in the
-configuration file of all nodes. See the `oslo.messaging configuration
-<https://docs.openstack.org/oslo.messaging/latest/configuration/opts.html#oslo_messaging_notifications.transport_url>`_
-documentation for more details.
+a unified queue for notifications. This can be done in the configuration file
+of all nodes. Refer to the :oslo.messaging-doc:`oslo.messaging configuration
+documentation
+<configuration/opts.html#oslo_messaging_notifications.transport_url>` for more
+details.
 
 Neutron Metadata API proxy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/user/flavors.rst b/doc/source/user/flavors.rst
index 4d10a66beb..efed65cb57 100644
--- a/doc/source/user/flavors.rst
+++ b/doc/source/user/flavors.rst
@@ -63,12 +63,10 @@ RXTX Factor
 
   .. note::
 
-     This property only applies if using the `xen` compute driver with the
-     `nova-network` network driver. It will likely be deprecated in a future
-     release. `neutron` users should refer to the `neutron QoS
-     documentation`__.
-
-     __ https://docs.openstack.org/neutron/latest/admin/config-qos.html
+     This property only applies if using the ``xen`` compute driver with the
+     ``nova-network`` network driver. It will likely be deprecated in a future
+     release. ``neutron`` users should refer to the :neutron-doc:`neutron QoS
+     documentation <admin/config-qos.html>`
 
 Is Public
   Boolean value that defines whether the flavor is available to all users or
diff --git a/doc/source/user/launch-instance-from-volume.rst b/doc/source/user/launch-instance-from-volume.rst
index e16e931a12..618dae6a8f 100644
--- a/doc/source/user/launch-instance-from-volume.rst
+++ b/doc/source/user/launch-instance-from-volume.rst
@@ -35,10 +35,10 @@ To complete these tasks, use these parameters on the
 
 .. note::
 
-   To attach a volume to a running instance, see
-   `Attach a volume to an instance`_.
+   To attach a volume to a running instance, refer to the
+   :cinder-doc:`Cinder documentation
+   <cli/cli-manage-volumes.html#attach-a-volume-to-an-instance>`.
 
-.. _Attach a volume to an instance: https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html#attach-a-volume-to-an-instance
 .. _Boot_instance_from_image_and_attach_non-bootable_volume:
 
 Boot instance from image and attach non-bootable volume
@@ -293,8 +293,8 @@ the volume to boot an instance.
 
 
    This requires an encrypted volume type, which must be created ahead of
-   time by an admin.  See
-   `Create an encrypted volume type <https://docs.openstack.org/horizon/latest/admin/manage-volumes.html#create-an-encrypted-volume-type>`_
+   time by an admin.  Refer to
+   :horizon-doc:`admin/manage-volumes.html#create-an-encrypted-volume-type`.
    in the OpenStack Horizon Administration Guide.
 
 #. Create a VM from previously created bootable volume. The volume is not
diff --git a/nova/api/openstack/compute/rest_api_version_history.rst b/nova/api/openstack/compute/rest_api_version_history.rst
index b1042f22fb..4d7cd47b9b 100644
--- a/nova/api/openstack/compute/rest_api_version_history.rst
+++ b/nova/api/openstack/compute/rest_api_version_history.rst
@@ -758,6 +758,8 @@ Added pagination support for migrations, there are four changes:
 * The query parameter schema of the ``GET /os-migrations`` API no longer
   allows additional properties.
 
+.. _api-microversion-queens:
+
 2.60 (Maximum in Queens)
 ------------------------
 
diff --git a/placement-api-ref/source/conf.py b/placement-api-ref/source/conf.py
index 536f02cdd0..f52d3fdbd0 100644
--- a/placement-api-ref/source/conf.py
+++ b/placement-api-ref/source/conf.py
@@ -88,3 +88,9 @@ latex_documents = [
     ('index', 'Placement.tex', u'OpenStack Placement API Documentation',
      u'OpenStack Foundation', 'manual'),
 ]
+
+# -- Options for openstackdocstheme -------------------------------------------
+
+openstack_projects = [
+    'nova',
+]
diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst
index fe0feee27f..d09315b8ef 100644
--- a/placement-api-ref/source/index.rst
+++ b/placement-api-ref/source/index.rst
@@ -5,8 +5,8 @@
 ===============
 
 This is a reference for the OpenStack Placement API. To learn more about
-OpenStack Placement API concepts, please refer to the
-`Placement Introduction <https://docs.openstack.org/nova/latest/user/placement.html>`_.
+OpenStack Placement API concepts, please refer to the :nova-doc:`Placement
+Introduction <user/placement.html>`.
 
 The Placement API uses JSON for data exchange.  As such, the ``Content-Type``
 header for APIs sending data payloads in the request body (i.e. ``PUT`` and