tox: Document and dedupe mostly everything

Take advantage of tox's expressiveness to avoid duplication wherever
possible and document the many targets we have.

Change-Id: I33675b7eedcffcebf1115dd48757874cb73f3e2f
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 2.1
-envlist = py{35,27},functional,pep8,pip-missing-reqs
+envlist = py{27,35},functional,pep8,pip-missing-reqs
 skipsdist = True
 
 [testenv]
@@ -22,7 +22,8 @@ setenv =
 deps = -r{toxinidir}/test-requirements.txt
 commands =
   find . -type f -name "*.pyc" -delete
-passenv = OS_DEBUG GENERATE_HASHES
+passenv =
+  OS_DEBUG GENERATE_HASHES
 # there is also secret magic in subunit-trace which lets you run in a fail only
 # mode. To do this define the TRACE_FAILONLY environmental variable.
 
@@ -47,11 +48,11 @@ commands =
 # TODO(efried): Remove this once https://github.com/tox-dev/tox/issues/425 is fixed.
 basepython = python3.6
 commands =
-  {[testenv]commands}
+  {[testenv:py35]commands}
-  stestr run --blacklist-file=tests-py3.txt {posargs}
-  env TEST_OSPROFILER=1 stestr run --combine --no-discover 'nova.tests.unit.test_profiler'
 
 [testenv:pep8]
+description =
+  Run style checks.
 deps = {[testenv]deps}
 commands =
   bash tools/flake8wrap.sh {posargs}
@@ -61,10 +62,8 @@ commands =
   bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
 
 [testenv:fast8]
-# This is a subset of the full pep8 check which
+description =
-# only runs flake8 on the changes made since
+  Run style checks on the changes made since HEAD~. For a full run including docs, use 'pep8'
-# HEAD-1. For a full flake8 run including checking
-# docs, just use pep8.
 commands =
   bash tools/flake8wrap.sh -HEAD
 
@@ -92,16 +91,7 @@ commands =
 basepython = python3.5
 setenv = {[testenv]setenv}
 commands =
-  {[testenv]commands}
+  {[testenv:functional]commands}
-# NOTE(cdent): The group_regex describes how stestr will group tests into the
-# same process when running concurently. The following ensures that gabbi tests
-# coming from the same YAML file are all in the same process. This is important
-# because each YAML file represents an ordered sequence of HTTP requests. Note
-# that tests which do not match this regex will not be grouped in any
-# special way. See the following for more details.
-# http://stestr.readthedocs.io/en/latest/MANUAL.html#grouping-tests
-# https://gabbi.readthedocs.io/en/latest/#purpose
-  stestr --test-path=./nova/tests/functional --group_regex=nova\.tests\.functional\.api\.openstack\.placement\.test_placement_api(?:\.|_)([^_]+) run {posargs}
 
 [testenv:api-samples]
 setenv =
@@ -109,27 +99,33 @@ setenv =
   GENERATE_SAMPLES=True
   PYTHONHASHSEED=0
 commands =
-  find . -type f -name "*.pyc" -delete
+  {[testenv]commands}
   stestr --test-path=./nova/tests/functional/api_sample_tests run {posargs}
   stestr slowest
 
 [testenv:genconfig]
-commands = oslo-config-generator --config-file=etc/nova/nova-config-generator.conf
+commands =
+  oslo-config-generator --config-file=etc/nova/nova-config-generator.conf
 
 [testenv:genpolicy]
-commands = oslopolicy-sample-generator --config-file=etc/nova/nova-policy-generator.conf
+commands =
+  oslopolicy-sample-generator --config-file=etc/nova/nova-policy-generator.conf
 
 [testenv:genplacementpolicy]
-commands = oslopolicy-sample-generator --config-file=etc/nova/placement-policy-generator.conf
+commands =
+  oslopolicy-sample-generator --config-file=etc/nova/placement-policy-generator.conf
 
 [testenv:cover]
-# Also do not run test_coverage_ext tests while gathering coverage as those
+# TODO(stephenfin): Remove the PYTHON hack below in favour of a [coverage]
-# tests conflict with coverage.
+# section once we rely on coverage 4.3+
-setenv = {[testenv]setenv}
+#
-         PYTHON=coverage run --source nova --parallel-mode
+# https://bitbucket.org/ned/coveragepy/issues/519/
+setenv =
+  {[testenv]setenv}
+  PYTHON=coverage run --source nova --parallel-mode
 commands =
+  {[testenv]commands}
   coverage erase
-  find . -type f -name "*.pyc" -delete
   stestr run {posargs}
   coverage combine
   coverage html -d cover
@@ -138,67 +134,72 @@ commands =
 
 [testenv:debug]
 commands =
-  find . -type f -name "*.pyc" -delete
+  {[testenv]commands}
   oslo_debug_helper {posargs}
 
 [testenv:venv]
 deps =
   -r{toxinidir}/test-requirements.txt
   -r{toxinidir}/doc/requirements.txt
-commands = {posargs}
+commands =
+  {posargs}
 
 [testenv:docs]
+description =
+  Build all documentation including API guides and refs.
 deps = -r{toxinidir}/doc/requirements.txt
 commands =
-  rm -rf doc/source/api doc/build api-guide/build api-ref/build placement-api-ref/build
+  rm -rf doc/build
   # 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]commands}
+  {[testenv:api-ref]commands}
+  {[testenv:placement-api-ref]commands}
 
 [testenv:api-guide]
-# This environment is called from CI scripts to test and publish
+description =
-# the API Guide to developer.openstack.org.
+  Generate the API guide. Called from CI scripts to test and publish to developer.openstack.org.
-deps = -r{toxinidir}/doc/requirements.txt
+deps = {[testenv:docs]deps}
 commands =
+  rm -rf api-guide/build
   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
+description =
-# the API Ref to developer.openstack.org.
+  Generate the API ref. Called from CI scripts to test and publish to developer.openstack.org.
-deps = -r{toxinidir}/doc/requirements.txt
+deps = {[testenv:docs]deps}
 commands =
   rm -rf api-ref/build
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:placement-api-ref]
-# This environment is called from CI scripts to test and publish
+description =
-# the Placement API Ref to developer.openstack.org.
+  Generate the Placement API ref. Called from CI scripts to test and publish to developer.openstack.org.
-deps = -r{toxinidir}/doc/requirements.txt
+deps = {[testenv:docs]deps}
 commands =
   # Check that all placement api routes are in the documentation
   python tools/placement_api_docs.py placement-api-ref/source/
   rm -rf placement-api-ref/build
   sphinx-build -W -b html -d placement-api-ref/build/doctrees placement-api-ref/source placement-api-ref/build/html
 
+[testenv:releasenotes]
+description =
+  Generate release notes.
+deps = {[testenv:docs]deps}
+commands =
+  rm -rf releasenotes/build
+  sphinx-build -W -b html -d releasenotes/build/doctrees releasenotes/source releasenotes/build/html
+
 [testenv:bandit]
 # NOTE(browne): This is required for the integration test job of the bandit
 # project. Please do not remove.
 commands = bandit -r nova -x tests -n 5 -ll
 
-[testenv:releasenotes]
-deps = -r{toxinidir}/doc/requirements.txt
-commands =
-  rm -rf releasenotes/build
-  sphinx-build -W -b html -d releasenotes/build/doctrees releasenotes/source releasenotes/build/html
-
 [flake8]
 # E125 is deliberately excluded. See
 # https://github.com/jcrocholl/pep8/issues/126. It's just wrong.
@@ -213,7 +214,6 @@ commands =
 # line. Rejecting code for this reason is wrong.
 #
 # E251 Skipped due to https://github.com/jcrocholl/pep8/issues/301
-
 enable-extensions = H106,H203,H904
 ignore = E121,E122,E123,E124,E125,E126,E127,E128,E129,E131,E251,H405
 exclude =  .venv,.git,.tox,dist,*lib/python*,*egg,build,tools/xenserver*,releasenotes
@@ -234,9 +234,10 @@ import_exceptions = nova.i18n
 # separately, outside of the requirements files, and develop mode disabled
 # explicitly to avoid unnecessarily installing the checked-out repo too (this
 # further relies on "tox.skipsdist = True" above).
-deps = bindep
-commands = bindep test
 usedevelop = False
+deps = bindep
+commands =
+  bindep test
 
 [testenv:lower-constraints]
 deps =
@@ -244,5 +245,5 @@ deps =
   -r{toxinidir}/test-requirements.txt
   -r{toxinidir}/requirements.txt
 commands =
-    {[testenv]commands}
+  {[testenv]commands}
-    stestr run --blacklist-file=tests-py3.txt {posargs}
+  stestr run --blacklist-file=tests-py3.txt {posargs}