diff --git a/doc/source/conf.py b/doc/source/conf.py
index 930b6b8..9f37578 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -33,12 +33,12 @@ sys.path.insert(0, os.path.abspath('../..'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
-    'oslosphinx',
+    'openstackdocstheme',
     'yasfb',
 ]
 
+repository_name = 'openstack/oslo-specs'
+
 # Feed configuration for yasfb
 feed_base_url = 'http://specs.openstack.org/openstack/oslo-specs'
 feed_author = 'OpenStack Oslo Team'
@@ -89,6 +89,7 @@ pygments_style = 'sphinx'
 # html_theme_path = ["."]
 # html_theme = '_theme'
 # html_static_path = ['static']
+html_theme = 'openstackdocs'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
diff --git a/requirements.txt b/requirements.txt
index 7ee61bb..abe9d3e 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,7 @@
 pbr>=0.6,<1.0
-oslosphinx
-sphinx>=1.1.2,!=1.2.0,<1.3
-yasfb>=0.5.0
+openstackdocstheme>=1.20.0
+sphinx!=1.6.6,>=1.6.2
+yasfb>=0.8.0
 simplejson>=2.2.0
 pyOpenSSL>=0.14  # Apache-2.0
 pyasn1  # BSD
diff --git a/specs/liberty/privsep.rst b/specs/liberty/privsep.rst
index 2cd935d..82a56fa 100644
--- a/specs/liberty/privsep.rst
+++ b/specs/liberty/privsep.rst
@@ -349,7 +349,7 @@ Code coverage
 .............
 
 ``coverage.py`` has support for collecting coverage statistics across
-sub-processes[#coverage_subproc].  To do this, the privileged process
+sub-processes [#coverage_subproc]_.  To do this, the privileged process
 will need to call ``coverage.process_startup()`` as early as possible
 (eg: from ``main()``), which enables coverage features if the
 ``COVERAGE_PROCESS_START`` environment variable is set.  If the
diff --git a/specs/mitaka/rabbitmq-pika-driver.rst b/specs/mitaka/rabbitmq-pika-driver.rst
index a90a382..e6bed9e 100644
--- a/specs/mitaka/rabbitmq-pika-driver.rst
+++ b/specs/mitaka/rabbitmq-pika-driver.rst
@@ -256,8 +256,8 @@ pika library
 References
 ==========
 
-.. [1] https://github.com/dukhlov/oslo.messaging/blob/master/oslo_messaging/_drivers/impl_pika.py
-.. [2] https://review.openstack.org/#/c/226348/
+#. https://github.com/dukhlov/oslo.messaging/blob/master/oslo_messaging/_drivers/impl_pika.py
+#. https://review.openstack.org/#/c/226348/
 
 .. note::
 
diff --git a/specs/queens/external-pdp.rst b/specs/queens/external-pdp.rst
index 1862921..00434a1 100644
--- a/specs/queens/external-pdp.rst
+++ b/specs/queens/external-pdp.rst
@@ -64,9 +64,7 @@ User will be able to choose between:
 The switch between those PDP can be configured and done through the modification of policy.json/yaml.
 For each rule, a URL need to be set.
 Thus every components that use Oslo_Policy can benefit from this improvement. For example in Glance
-policy.json file:
-
-.. code-block:: json
+policy.json file::
 
     {
         "context_is_admin":  "role:admin",