devref: consider sphinx warnings as failures

We previously introduced issues in our documentation due to not checking
for sphinx warnings [1], so let's enforce documentation validation.

This commit also fixes minor syntax issues caught by sphinx. Among
those, contribute.rst is now properly attached to ToC.

[1]: I48ab899077458d99eee6f643577d574106c1ca88

Change-Id: I9170883a20137c343f03d8b052399eacab4ae130

TESTING.rst

@@ -64,7 +64,7 @@ tests in a virtualenv::
 
 
 With `nose2`
-~~~~~~~~~~~
+~~~~~~~~~~~~
 
 You can use `nose2`_ to run individual tests, as well as use for debugging
 portions of your code::

doc/source/devref/development.environment.rst

@@ -47,5 +47,3 @@ Grab the code::
 
 
 .. include:: ../../../TESTING.rst
-
-.. include:: ./contribute.rst

doc/source/devref/index.rst

@@ -30,6 +30,7 @@ Programming HowTos and Tutorials
     :maxdepth: 3
 
     development.environment
+    contribute
 
 
 Neutron Internals

tox.ini

@@ -65,7 +65,7 @@ commands =
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build
 
 [flake8]
 # E125 continuation line does not distinguish itself from next logical line