Move doc requirements to doc/requirements.txt

Put these in place as a setup for the new versions of the doc build
jobs. Keep using them from the normal dep list until the jobs are
changed.

While we're here, update the docs env to use sphinx-build instead of
python setup.py build_sphinx. Also add python2.7 to the docs env, since
I accidentally tried building it with my python3 tox and it blew up
substantially.

Change-Id: I0fcc50c4c396758e839c329ce786a6f609bb1342

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=1.6.2 # BSD
+openstackdocstheme>=1.17.0 # Apache-2.0

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

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

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