diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000000..de9a2f53ad
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,8 @@
+# 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.
+# this is required for the docs build jobs
+sphinx>=1.6.2 # BSD
+openstackdocstheme>=1.11.0 # Apache-2.0
+reno>=1.8.0  # Apache-2.0
+os-api-ref>=1.0.0 # Apache-2.0
diff --git a/setup.cfg b/setup.cfg
index 1e5fdbeeb3..3cfdfc068c 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -111,11 +111,6 @@ paste.filter_factory =
     listing_formats = swift.common.middleware.listing_formats:filter_factory
     symlink = swift.common.middleware.symlink:filter_factory
 
-[build_sphinx]
-all_files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
 
 [egg_info]
 tag_build =
diff --git a/test-requirements.txt b/test-requirements.txt
index 968571a236..dc1e5dabc6 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -8,14 +8,10 @@ coverage>=3.6 # Apache-2.0
 nose # LGPL
 nosexcover # BSD
 nosehtmloutput>=0.0.3 # Apache-2.0
-sphinx>=1.6.2 # BSD
-openstackdocstheme>=1.11.0 # Apache-2.0
-os-api-ref>=1.0.0 # Apache-2.0
 os-testr>=0.8.0 # Apache-2.0
 mock>=2.0 # BSD
 python-swiftclient
 python-keystoneclient!=2.1.0,>=2.0.0 # Apache-2.0
-reno>=1.8.0  # Apache-2.0
 
 # Security checks
 bandit>=1.1.0 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index c335d36cd5..2cbaa6bb82 100644
--- a/tox.ini
+++ b/tox.ini
@@ -92,15 +92,14 @@ commands = {posargs}
 
 [testenv:docs]
 basepython = python2.7
-commands = python setup.py build_sphinx
+deps = -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.
-# we do not use -W here because we are doing some slightly tricky
-# things to build a single page document, and as such, we are ok
-# ignoring the duplicate stanzas warning.
 basepython = python2.7
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf api-ref/build
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
@@ -132,4 +131,5 @@ deps = bindep
 commands = bindep test
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = sphinx-build -a -W -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html