tox: Keeping going with docs

Sphinx 1.8 introduced [1] the '--keep-going' argument which, as its name
suggests, keeps the build running when it encounters non-fatal errors.
This is exceptionally useful in avoiding a continuous edit-build loop
when undertaking large doc reworks where multiple errors may be
introduced.

[1] https://github.com/sphinx-doc/sphinx/commit/e3483e9b045

Change-Id: I96e52fe2f0b14d359f37964c3bd51b1ba985dac0

doc/requirements.txt

@@ -1,4 +1,8 @@
-sphinx>=1.7.0,<2.0.0;python_version=='2.7' # BSD
-sphinx>=1.7.0;python_version>='3.4' # BSD
+# 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.
+
+sphinx>=1.8.0,<2.0.0;python_version=='2.7' # BSD
+sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD
 openstackdocstheme>=1.20.0 # Apache-2.0
 os-api-ref>=1.5.0 # Apache-2.0

lower-constraints.txt

@@ -103,7 +103,7 @@ Routes==2.4.1
 simplejson==3.13.2
 six==1.11.0
 snowballstemmer==1.2.1
-Sphinx==1.7.0
+Sphinx==1.8.0
 sphinxcontrib-websupport==1.0.1
 SQLAlchemy==1.2.5
 sqlalchemy-migrate==0.11.0

tox.ini

@@ -35,7 +35,7 @@ deps =
   -r{toxinidir}/doc/requirements.txt
 commands =
   rm -rf doc/build
-  sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
+  sphinx-build -W --keep-going -b html -d doc/build/doctrees doc/source doc/build/html
 
 [testenv:api-ref]
 # This environment is called from CI scripts to test and publish
@@ -44,7 +44,7 @@ whitelist_externals = rm
 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
+  sphinx-build -W --keep-going -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [flake8]
 # E712 is ignored on purpose, since it is normal to use 'column == true'