diff --git a/.gitignore b/.gitignore
index 2bee082dcd..fe9c74b77f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,4 @@ dist
 .eggs
 *.egg
 *.pot
+doc/build
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000000..d2a556bbfc
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,3 @@
+# this is required for the docs build jobs
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+openstackdocstheme>=1.18.1 # Apache-2.0
diff --git a/test-requirements.txt b/test-requirements.txt
index beeea49255..2e078495fb 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -10,8 +10,3 @@ virtualenv>=14.0.6 # MIT
 setuptools!=24.0.0,!=34.0.0,!=34.0.1,!=34.0.2,!=34.0.3,!=34.1.0,!=34.1.1,!=34.2.0,!=34.3.0,!=34.3.1,!=34.3.2,!=36.2.0,>=21.0.0 # PSF/ZPL
 mock>=2.0.0 # BSD
 bashate>=0.5.1 # Apache-2.0
-
-# this is required for the docs build jobs
-sphinx!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7'  # BSD
-sphinx!=1.6.6,!=1.6.7;python_version>='3.4'  # BSD
-openstackdocstheme>=1.18.1 # Apache-2.0
diff --git a/tox.ini b/tox.ini
index 22db546649..5aa2d7e97f 100644
--- a/tox.ini
+++ b/tox.ini
@@ -72,7 +72,9 @@ commands = bindep test
 usedevelop = False
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+deps = -c{env:UPPER_CONSTRAINTS_FILE:{toxinidir}/upper-constraints.txt}
+       -r{toxinidir}/doc/requirements.txt
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:pip-install]
 recreate = True