diff --git a/doc/requirements.txt b/doc/requirements.txt
index 77fc36cae..a6bb0d587 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/conf.py b/doc/source/conf.py
index 61d485040..b163e8d72 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/placement.rst b/doc/source/contributor/placement.rst
index 12773d1dd..faa282048 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/index.rst b/doc/source/index.rst
index fec5c4b27..86191a97b 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/controller-install-obs.rst b/doc/source/install/controller-install-obs.rst
index eabdee96c..9ced92acc 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 15d2f51e0..b3217ea4a 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 c7a50c67c..c97d9d8ad 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/placement-api-ref/source/conf.py b/placement-api-ref/source/conf.py
index 536f02cdd..f52d3fdbd 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 fe0feee27..d09315b8e 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