diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000..4faabc1b0
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,7 @@
+# The order of packages is significant, because pip processes them in the order
+# of appearance. Changing the order has an impact on the overall integration
+# process, which may cause wedges in the gate later.
+openstackdocstheme>=1.18.1 # Apache-2.0
+reno>=2.5.0 # Apache-2.0
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-apidoc>=0.2.0  # BSD
diff --git a/doc/source/api_v1.rst b/doc/source/api_v1.rst
index eb29c2812..f3dea2cde 100644
--- a/doc/source/api_v1.rst
+++ b/doc/source/api_v1.rst
@@ -96,11 +96,7 @@ Refer to the modules themselves, for more details.
 ironicclient Modules
 ====================
 
-.. toctree::
-    :maxdepth: 1
-
-    modules <api/autoindex>
-
+* :ref:`modindex`
 
 .. _ironicclient.v1.node: api/ironicclient.v1.node.html#ironicclient.v1.node.Node
 .. _ironicclient.v1.client.Client: api/ironicclient.v1.client.html#ironicclient.v1.client.Client
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 270cc7942..355645454 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -2,12 +2,21 @@
 
 # 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',
+extensions = ['sphinxcontrib.apidoc',
               'sphinx.ext.viewcode',
               'openstackdocstheme',
               'cliff.sphinxext',
               ]
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../ironicclient'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = [
+    'tests/functional/*',
+    'tests']
+apidoc_separate_modules = True
+
+
 # openstackdocstheme options
 repository_name = 'openstack/python-ironicclient'
 bug_project = 'python-ironicclient'
diff --git a/setup.cfg b/setup.cfg
index 3f777b574..aa35190bf 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -103,17 +103,6 @@ openstack.baremetal.v1 =
     baremetal_volume_target_show = ironicclient.osc.v1.baremetal_volume_target:ShowBaremetalVolumeTarget
     baremetal_volume_target_unset = ironicclient.osc.v1.baremetal_volume_target:UnsetBaremetalVolumeTarget
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-    ironicclient.tests.functional.*
-warnerrors = True
-
-[build_sphinx]
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
 
 [wheel]
 universal = 1
diff --git a/test-requirements.txt b/test-requirements.txt
index 6ac42b33e..c07ebed3c 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -8,10 +8,7 @@ fixtures>=3.0.0 # Apache-2.0/BSD
 requests-mock>=1.2.0 # Apache-2.0
 mock>=2.0.0 # BSD
 Babel!=2.4.0,>=2.3.4 # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 testtools>=2.2.0 # MIT
 tempest>=17.1.0 # Apache-2.0
 os-testr>=1.0.0 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index 1a3ed7ed6..90b368058 100644
--- a/tox.ini
+++ b/tox.ini
@@ -19,6 +19,10 @@ commands =
     ostestr {posargs}
 
 [testenv:releasenotes]
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [testenv:pep8]
@@ -37,6 +41,11 @@ commands =
   coverage html -d ./cover --omit='*tests*'
 
 [testenv:venv]
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands = {posargs}
 
 [testenv:functional]
@@ -44,11 +53,12 @@ setenv = TESTS_DIR=./ironicclient/tests/functional
          LANGUAGE=en_US
 
 [testenv:docs]
-setenv = PYTHONHASHSEED=0
-sitepackages = False
-envdir = {toxworkdir}/venv
+deps =
+  -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
+  -r{toxinidir}/requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands =
-  python setup.py build_sphinx
+  sphinx-build -W -b html doc/source doc/build/html
 
 [flake8]
 ignore =