diff --git a/README.rst b/README.rst
index 64dbebb..d7ee87a 100644
--- a/README.rst
+++ b/README.rst
@@ -17,19 +17,22 @@ This is an OpenStack Client (OSC) plugin for Octavia, an OpenStack
 Load Balancing project.
 
 For more information about Octavia see:
-http://docs.openstack.org/developer/octavia
+https://docs.openstack.org/octavia/latest/
 
 For more information about the OpenStack Client see:
-https://docs.openstack.org/developer/python-openstackclient
+https://docs.openstack.org/python-openstackclient/latest/
 
 * Free software: Apache license
-* Documentation: http://docs.openstack.org/developer/python-octaviaclient
+* Documentation: https://docs.openstack.org/octavia/latest/
 * Source: http://git.openstack.org/cgit/openstack/python-octaviaclient
 * Bugs: http://bugs.launchpad.net/octavia
 
 Getting Started
 ===============
 
+.. note:: This is an OpenStack Client plugin.  The ``python-openstackclient``
+          project should be installed to use this plugin.
+
 Octavia client can be installed from PyPI using pip::
 
     pip install python-octaviaclient
diff --git a/doc/source/usage/osc_cli_plugins.rst b/doc/source/cli/index.rst
similarity index 100%
rename from doc/source/usage/osc_cli_plugins.rst
rename to doc/source/cli/index.rst
diff --git a/doc/source/usage/osc/v2/load-balancer.rst b/doc/source/cli/osc/v2/load-balancer.rst
similarity index 100%
rename from doc/source/usage/osc/v2/load-balancer.rst
rename to doc/source/cli/osc/v2/load-balancer.rst
diff --git a/doc/source/conf.py b/doc/source/conf.py
index e099948..b6e8afc 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,8 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'openstackdocstheme'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -58,6 +57,8 @@ pygments_style = 'sphinx'
 # html_theme = '_theme'
 # html_static_path = ['static']
 
+html_theme = 'openstackdocs'
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
@@ -73,3 +74,10 @@ latex_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+
+# openstackdocstheme options
+repository_name = 'openstack/python-octaviaclient'
+bug_project = 'octavia'
+bug_tag = 'doc'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
diff --git a/doc/source/contributing.rst b/doc/source/contributor/index.rst
similarity index 50%
rename from doc/source/contributing.rst
rename to doc/source/contributor/index.rst
index 1728a61..2aa0707 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributor/index.rst
@@ -1,4 +1,4 @@
 ============
 Contributing
 ============
-.. include:: ../../CONTRIBUTING.rst
+.. include:: ../../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c26b79b..864c5d5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -15,9 +15,9 @@ Getting Started
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   contributing
+   Project Overview <readme>
+   install/index
+   contributor/index
 
 Usage
 -----
@@ -25,12 +25,11 @@ Usage
 .. toctree::
    :maxdepth: 2
 
-   usage/osc_cli_plugins
-   decoder
+   cli/index
+   reference/index
 
 Indices and tables
 ------------------
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
new file mode 100644
index 0000000..d4a4fbd
--- /dev/null
+++ b/doc/source/install/index.rst
@@ -0,0 +1,17 @@
+============
+Installation
+============
+
+This is an OpenStack Client plugin for the load-balancer (Octavia) project.
+
+Install the load-balancer (Octavia) plugin::
+
+    $ pip install python-octaviaclient
+
+Or, if you have virtualenvwrapper installed::
+
+    $ mkvirtualenv python-octaviaclient
+    $ pip install python-octaviaclient
+
+.. note:: If python-openstackclient is not already installed it will be
+          installed as part of the requirements for the Octavia client plugin.
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
deleted file mode 100644
index 2c915d3..0000000
--- a/doc/source/installation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install python-octaviaclient
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv python-octaviaclient
-    $ pip install python-octaviaclient
diff --git a/doc/source/data/lbaas.csv b/doc/source/reference/data/lbaas.csv
similarity index 100%
rename from doc/source/data/lbaas.csv
rename to doc/source/reference/data/lbaas.csv
diff --git a/doc/source/decoder.rst b/doc/source/reference/decoder.rst
similarity index 94%
rename from doc/source/decoder.rst
rename to doc/source/reference/decoder.rst
index 04c495f..d03f156 100644
--- a/doc/source/decoder.rst
+++ b/doc/source/reference/decoder.rst
@@ -6,8 +6,8 @@ the Octavia plugin into OSC. Think of it as a magic decoder ring if you were
 using the legacy CLIs and want to transition to OpenStack CLI.
 Command options are only shown when necessary.
 
-``LBaaS v2 CLI``
-----------------
+LBaaS v2 CLI
+------------
 
 .. csv-table::
    :header: "Neutron CLI", "OSC Equivalent", "Description"
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..4aec59d
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,7 @@
+Python Octavia Client Reference
+===============================
+
+.. toctree::
+   :maxdepth: 2
+
+   decoder
diff --git a/setup.cfg b/setup.cfg
index f1a5533..7405311 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -5,7 +5,7 @@ description-file =
     README.rst
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
-home-page = http://docs.openstack.org/developer/python-octaviaclient
+home-page = https://docs.openstack.org/python-octaviaclient/latest/
 classifier =
     Environment :: OpenStack
     Intended Audience :: Information Technology
@@ -67,6 +67,7 @@ openstack.load_balancer.v2 =
 source-dir = doc/source
 build-dir = doc/build
 all_files = 1
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html
diff --git a/test-requirements.txt b/test-requirements.txt
index cf0c5a0..c497fb0 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -11,7 +11,7 @@ keystoneauth1>=2.21.0 # Apache-2.0
 python-subunit>=0.0.18 # Apache-2.0/BSD
 python-openstackclient!=3.10.0,>=3.3.0 # Apache-2.0
 sphinx>=1.6.2 # BSD
-oslosphinx>=4.7.0 # Apache-2.0
+openstackdocstheme>=1.16.0  # Apache-2.0
 oslotest>=1.10.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD