Use sphinx-build -W in [docs] target

Also, fixes some existing warnings.

The idea was taken from https://review.openstack.org/#/c/251077/ .

Change-Id: I5948e470c0db0b3419404da61dd906998c8f4754

specs/kilo/agent.rst

@@ -60,9 +60,8 @@ provide:
    field of the API.
  * 'configurations': A dictionary that includes configurations specific to the
    agent.  For MidoNet, this dictionary contains the IP addresses and the
-   interfaces of the host:
+   interfaces of the host::
 
-::
         {
             "interfaces":
                 [

specs/kilo/data_sync.rst

@@ -124,9 +124,11 @@ The data sync operation is implemented as follows:
     midonet-db-manage sets 'sync_started_at' to the current time, and
     'sync_tasks_status' and 'sync_status' to STARTED.  Syncing is disallowed in
     the following cases:
+
         a. Sync is already being executed
         b. There are unprocessed tasks (so that truncate does not delete
            unprocessed tasks)
+
  2. Immediately following the DATA_VERSION_SYNC task insertion,
     midonet-db-manage queries Neutron DB and generates CREATE tasks for all the
     existing resources.  Cluster processes them as usual and creates these

specs/kilo/port_binding.rst

@@ -72,9 +72,8 @@ the scope of this document.
 REST API
 --------
 
-An example of a port binding attributes in the request to create a port is:
+An example of a port binding attributes in the request to create a port is::
 
-::
   {
     "binding:host_id": "HOST_ID",
     "binding:profile": {"interface_name": "eth0"}

tox.ini

@@ -30,7 +30,7 @@ commands =
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:genconfig]
 deps = -r{toxinidir}/requirements.txt