diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 00000000..3c822d2c
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=1.6.2 # BSD
+openstackdocstheme>=1.17.0 # Apache-2.0
diff --git a/setup.cfg b/setup.cfg
index 19904b07..9aba8f83 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -16,17 +16,6 @@ classifier =
     Intended Audience :: Developers
     Environment :: Console
 
-[extras]
-# make openstackdocstheme an optional dependency. cliff is a low level lib
-# that is used outside of OpenStack. Not having something OpenStack specific
-# as build requirement is a good thing.
-docs =
-  openstackdocstheme>=1.17.0 # Apache-2.0
-
-[global]
-setup-hooks =
-    pbr.hooks.setup_hook
-
 [files]
 packages =
     cliff
diff --git a/test-requirements.txt b/test-requirements.txt
index 0628fbdd..dbb64027 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -10,7 +10,8 @@ testscenarios>=0.4 # Apache-2.0/BSD
 
 coverage!=4.4,>=4.0 # Apache-2.0
 
-# this is required for the docs build jobs
+# sphinx is required in test-requirements in addition to doc/requirements
+# because there is a sphinx extension that has tests
 sphinx>=1.6.2 # BSD
 
 # Bandit security code scanner
diff --git a/tox.ini b/tox.ini
index 929d28f1..30f261a3 100644
--- a/tox.ini
+++ b/tox.ini
@@ -31,6 +31,11 @@ commands =
   bandit -c bandit.yaml -r cliff -x tests -n5
 
 [testenv:venv]
+# TODO(modred) remove doc/requirements.txt once the openstack-build-sphinx-docs
+# job is updated.
+deps =
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands = {posargs}
 
 [testenv:neutronclient-tip]
@@ -44,4 +49,5 @@ deps = os:openstack/python-openstackclient:python-openstackclient
 commands = {toxinidir}/integration-tests/openstackclient-tip.sh {envdir}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+deps = -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -b html doc/source doc/build/html