diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000000..77d1fe88bf
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,7 @@
+openstackdocstheme>=1.18.1 # Apache-2.0
+os-api-ref>=1.4.0 # 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
+sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
+sphinxcontrib-seqdiag>=0.8.4 # BSD
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9c1ffe2781..313bb4ae90 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -24,12 +24,12 @@ except TypeError:
 
 # 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.viewcode',
+extensions = ['sphinx.ext.viewcode',
               'sphinx.ext.graphviz',
               'sphinxcontrib.httpdomain',
               'sphinxcontrib.pecanwsme.rest',
               'sphinxcontrib.seqdiag',
+              'sphinxcontrib.apidoc',
               'wsmeext.sphinxext',
               'oslo_config.sphinxext',
               'oslo_config.sphinxconfiggen',
@@ -43,6 +43,15 @@ try:
 except ImportError:
     openstackdocstheme = None
 
+# sphinxcontrib.apidoc options
+apidoc_module_dir = '../../ironic'
+apidoc_output_dir = 'contributor/api'
+apidoc_excluded_paths = [
+    'db/sqlalchemy/alembic/env'
+    'db/sqlalchemy/alembic/versions/*',
+    'drivers/modules/ansible/playbooks*']
+apidoc_separate_modules = True
+
 repository_name = 'openstack/ironic'
 bug_project = 'ironic'
 bug_tag = ''
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 94a347be39..73b33d9b83 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -91,10 +91,7 @@ booting from Cinder volumes with VMs.
 Full Ironic Server Python API Reference
 ---------------------------------------
 
-* :ref:`modindex`
-
-.. # api/autoindex is hidden since it's in the modindex link above.
 .. toctree::
-  :hidden:
+  :maxdepth: 1
 
-  api/autoindex
+  api/modules
diff --git a/setup.cfg b/setup.cfg
index 14c9221931..3c52c8f043 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -189,20 +189,6 @@ ironic.hardware.types =
 ironic.database.migration_backend =
     sqlalchemy = ironic.db.sqlalchemy.migration
 
-[pbr]
-autodoc_index_modules = True
-autodoc_exclude_modules =
-    ironic.db.sqlalchemy.alembic.env
-    ironic.db.sqlalchemy.alembic.versions.*
-    ironic.drivers.modules.ansible.playbooks*
-api_doc_dir = contributor/api
-
-[build_sphinx]
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
 [egg_info]
 tag_build =
 tag_date = 0
diff --git a/test-requirements.txt b/test-requirements.txt
index 558dddd2a6..eeea491e03 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -18,11 +18,3 @@ testscenarios>=0.4 # Apache-2.0/BSD
 WebTest>=2.0.27 # MIT
 bashate>=0.5.1 # Apache-2.0
 flake8-import-order>=0.13 # LGPLv3
-
-# Doc requirements
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0
-sphinxcontrib-seqdiag>=0.8.4 # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
-reno>=2.5.0 # Apache-2.0
-os-api-ref>=1.4.0 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index 3872ada4a1..0f4cb7d889 100644
--- a/tox.ini
+++ b/tox.ini
@@ -35,7 +35,7 @@ commands =
   # the check and gate queues.
   {toxinidir}/tools/run_bashate.sh {toxinidir}
   # Check the *.rst files
-  doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001
+  doc8 README.rst CONTRIBUTING.rst doc/source --ignore D001 --ignore D000
   # Check to make sure reno releasenotes created with 'reno new'
   {toxinidir}/tools/check-releasenotes.py
 
@@ -72,23 +72,27 @@ commands =
 commands = oslo_debug_helper -t ironic/tests/unit {posargs}
 
 [testenv:docs]
-# FIXME(dtantsur): workaround for bug #1714025
-basepython = python2
-setenv = PYTHONHASHSEED=0
-sitepackages = False
-envdir = {toxworkdir}/venv
-commands =
-  python setup.py build_sphinx
+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 -W -b html doc/source doc/build/html
 
 [testenv:api-ref]
-# This environment is called from CI scripts to test and publish
-# the API Ref to developer.openstack.org.
+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
 whitelist_externals = bash
 commands =
   bash -c 'rm -rf api-ref/build'
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [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