Follow the new PTI for document build

The Project Testing Interface [1] asks that we list requirements in
'doc/requirements.txt' and build docs by calling 'sphinx-build' directly
instead of via the 'build_sphinx' setuptool/distutils wrapper. Start
doing this.

[1] https://governance.openstack.org/tc/reference/project-testing-interface.html

Change-Id: If9342c8ea757b1735f2488db751008984fb33baf

doc/requirements.txt

@@ -0,0 +1,11 @@
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
+sphinxcontrib-actdiag>=0.8.5 # BSD
+sphinxcontrib-seqdiag>=0.8.4 # BSD
+os-api-ref>=1.4.0 # Apache-2.0
+openstackdocstheme>=1.18.1 # Apache-2.0
+
+# releasenotes
+reno>=2.5.0 # Apache-2.0
+
+# redirect tests in docs
+whereto>=0.3.0 # Apache-2.0

setup.cfg

@@ -92,13 +92,6 @@ nova.scheduler.driver =
     chance_scheduler = nova.scheduler.chance:ChanceScheduler
     fake_scheduler = nova.tests.unit.scheduler.fakes:FakeScheduler
 
-[build_sphinx]
-builder = html man
-all-files = 1
-build-dir = doc/build
-source-dir = doc/source
-warning-is-error = 1
-
 [egg_info]
 tag_build =
 tag_date = 0

test-requirements.txt

@@ -13,10 +13,6 @@ PyMySQL>=0.7.6 # MIT License
 python-barbicanclient>=4.5.2 # Apache-2.0
 python-ironicclient>=2.2.0 # Apache-2.0
 requests-mock>=1.1.0 # Apache-2.0
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
-sphinxcontrib-actdiag>=0.8.5 # BSD
-sphinxcontrib-seqdiag>=0.8.4 # BSD
-os-api-ref>=1.4.0 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
 stestr>=1.0.0 # Apache-2.0
 osprofiler>=1.4.0 # Apache-2.0
@@ -24,17 +20,10 @@ testresources>=2.0.0 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=2.2.0 # MIT
 bandit>=1.1.0 # Apache-2.0
-openstackdocstheme>=1.18.1 # Apache-2.0
 gabbi>=1.35.0 # Apache-2.0
 
 # vmwareapi driver specific dependencies
 oslo.vmware>=2.17.0 # Apache-2.0
 
-# releasenotes
-reno>=2.5.0 # Apache-2.0
-
 # placement functional tests
 wsgi-intercept>=1.4.1 # MIT License
-
-# redirect tests in docs
-whereto>=0.3.0 # Apache-2.0

tox.ini

@@ -135,34 +135,41 @@ commands =
   oslo_debug_helper {posargs}
 
 [testenv:venv]
+deps =
+  -r{toxinidir}/test-requirements.txt
+  -r{toxinidir}/doc/requirements.txt
 commands = {posargs}
 
 [testenv:docs]
 # TODO(melwitt): This can be removed when the docs target can be run
 # with python 3.x
 basepython = python2.7
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/source/api doc/build api-guide/build api-ref/build placement-api-ref/build
-  python setup.py build_sphinx
-  # Test the redirects
-  whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
   # Check that all JSON files don't have \r\n in line.
   bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'"
   # Check that all included JSON files are valid JSON
   bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
+  # Build docs
+  sphinx-build -W -b html doc/source doc/build/html
   sphinx-build -W -b html api-guide/source api-guide/build/html
   sphinx-build -W -b html api-ref/source api-ref/build/html
   sphinx-build -W -b html placement-api-ref/source placement-api-ref/build/html
+  # Test the redirects. This must run after the main docs build
+  whereto doc/build/html/.htaccess doc/test/redirect-tests.txt
 
 [testenv:api-guide]
 # This environment is called from CI scripts to test and publish
 # the API Guide to developer.openstack.org.
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   sphinx-build -W -b html -d api-guide/build/doctrees api-guide/source api-guide/build/html
 
 [testenv:api-ref]
 # This environment is called from CI scripts to test and publish
 # the API Ref to developer.openstack.org.
+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
@@ -170,6 +177,7 @@ commands =
 [testenv:placement-api-ref]
 # This environment is called from CI scripts to test and publish
 # the Placement API Ref to developer.openstack.org.
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
   # Check that all placement api routes are in the documentation
   python tools/placement_api_docs.py placement-api-ref/source/
@@ -182,6 +190,7 @@ commands =
 commands = bandit -r nova -x tests -n 5 -ll
 
 [testenv:releasenotes]
+deps = -r{toxinidir}/doc/requirements.txt
 commands = bash -c tools/releasenotes_tox.sh
 
 [flake8]