diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 00000000..592236b1
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx!=1.6.6,>=1.6.2 # BSD
+openstackdocstheme>=1.18.1 # Apache-2.0
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 8cb3146f..1f5ca23c 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1 +1,5 @@
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+============
+Contributing
+============
+
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5201159e..4bbfa540 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,7 +1,9 @@
+===============================================
 Welcome to python-magnumclient's documentation!
-==============================================
+===============================================
 
-Contents:
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
@@ -12,8 +14,7 @@ Contents:
    contributing
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index a6210d3d..5c280588 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1 +1,5 @@
+============
+Introduction
+============
+
 .. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 93c1f949..f6b411dc 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,3 +1,4 @@
+===========================================
 Python bindings to the OpenStack Magnum API
 ===========================================
 
diff --git a/setup.cfg b/setup.cfg
index 6a464b1a..c42a184d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -54,13 +54,6 @@ openstack.container_infra.v1 =
 
     coe_service_list = magnumclient.osc.v1.mservices:ListService
 
-[build_sphinx]
-source-dir = doc/source
-build-dir = doc/build
-all_files = 1
-
-[upload_sphinx]
-upload-dir = doc/build/html
 
 [compile_catalog]
 directory = magnumclient/locale
@@ -78,7 +71,3 @@ output_file = magnumclient/locale/magnumclient.pot
 
 [wheel]
 universal = 1
-
-[pbr]
-autodoc_index_modules = True
-warnerrors = True
diff --git a/test-requirements.txt b/test-requirements.txt
index 9062afab..72fed3f4 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -6,8 +6,6 @@ bandit>=1.1.0 # Apache-2.0
 coverage!=4.4,>=4.0 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 python-openstackclient>=3.12.0 # Apache-2.0
-sphinx!=1.6.6,>=1.6.2 # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
 osprofiler>=1.4.0 # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
diff --git a/tox.ini b/tox.ini
index 10652151..f19a3388 100644
--- a/tox.ini
+++ b/tox.ini
@@ -48,6 +48,11 @@ commands =
   # Run security linter
   bandit -r magnumclient -x tests -n5 -ll
 
+[testenv:docs]
+deps = -r{toxinidir}/doc/requirements.txt
+commands =
+  sphinx-build -W -b html doc/source doc/build/html
+
 [testenv:venv]
 commands = {posargs}