Use Sphinx 1.5 warning-is-error

With pbr 2.0 and Sphinx 1.5, the setting for treat sphinx warnings as
errors is setting warning-is-error in build_sphinx section. Migrate
the setting from the old warnerrors one.

Fix also problems found:
* code-blocks that could not be parsed
* Usage of :option: without declaring the option.
* Add blank lines to properly end markup.
* Fix a typo.
* Fix wrong markup of docstring
* Fix title underlinings.

Change-Id: I69ddde706a04f26bfccda072822dc0d230cb330e

doc/source/OSprofiler.rst

@@ -68,7 +68,8 @@ So In this example, we should add the following config options::
 
 .. note:: If you want to use MQ and Ceilometer, please leave the
    **connection_string** empty or indicate the MQ information. And please make
-   sure that the following config options have be set in Ceiolmeter.conf
+   sure that the following config options have be set in Ceilometer.conf
+
 ::
 
     [DEFAULT]
@@ -96,6 +97,7 @@ OpenStack Client will return a trace ID like::
     Trace ID: 2902c7a3-ee18-4b08-aae7-4e34388f9352
     Display trace with command:
     osprofiler trace show --html 2902c7a3-ee18-4b08-aae7-4e34388f9352
+
 Now the trace information has been stored in MongoDB already.
 
 2. Use the command from the openstack client return information. The osprofiler

doc/source/devref/development.environment.rst

@@ -235,7 +235,7 @@ Installing and using virtualenv
 .. note::
 
   You can run the Zaqar server in the background by passing the
-  :option:`--daemon` flag:
+  ``--daemon`` flag:
 
   .. code-block:: console
 
@@ -274,7 +274,7 @@ can add it to your DevStack_ deployment.
 
 To do this, you first need to add the following setting to your ``local.conf``:
 
-.. code-block:: ini
+.. code-block:: bash
 
   enable_plugin zaqar https://git.openstack.org/openstack/zaqar
 

doc/source/first_patch.rst

@@ -206,7 +206,7 @@ Common problems
     $ git checkout -b newbranch
     $ git commit -a -m "Edited"
 
-   If you already created the branch, omit the :option:`-b`.
+   If you already created the branch, omit the ``-b``.
 
    You put all your changes to :samp:`{newbranch}`. Problem solved.
 

doc/source/getting_started.rst

@@ -44,7 +44,7 @@ prerequisites:
 -  Basic familiarity with Cloud and RESTful APIs
 
 How Messaging service Works
--------------------------
+---------------------------
 
 Following is an overview of how Messaging service works. For definitions
 of Messaging service terms, see the below glossary.
@@ -138,7 +138,7 @@ This pattern is ideal for communicating with a specific client,
 especially when a reply is desired from that client.
 
 Messaging service Operations
---------------------------
+----------------------------
 
 This section lists all of the operations that are available in the
 Messaging service API. This document uses some of the most common
@@ -315,7 +315,7 @@ Following are some generic use cases for Messaging service:
    (RPC) agent (point-to-point messaging)
 
 Additional Resources
-====================
+--------------------
 
 For more information about using the API, see the Messaging service API v2
 Reference. All you need to get started with Messaging service is the
@@ -328,7 +328,7 @@ This API uses standard HTTP 1.1 response codes as documented at
 `www.w3.org/Protocols/rfc2616/rfc2616-sec10.html <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`__.
 
 Glossary
-========
+--------
 
 **Claim**
 The process of a worker checking out a message to perform a task.

doc/source/running_benchmark.rst

@@ -87,7 +87,7 @@ Usage
      $ zaqar-bench -pp 4 -pw 10 -cp 4 -cw 20 -ow 0 -t 30
 
    By default, the results are in human-readable format. For JSON output add
-   the :option:`--noverbose` flag. The non-verbose output looks similar to the
+   the ``--noverbose`` flag. The non-verbose output looks similar to the
    following:
 
    .. code-block:: console
@@ -99,7 +99,7 @@ Usage
      {"params": {"consumer": {"processes": 1, "workers": 0}, "observer": {"processes": 1, "workers": 5}, "producer": {"processes": 1, "workers": 10}}, "consumer": {"claim_total_requests": 0, "ms_per_claim": 0, "total_reqs": 0, "reqs_per_sec": 0, "successful_reqs": 0, "duration_sec": 0, "ms_per_delete": 0, "messages_processed": 0}, "producer": {"duration_sec": 8.569170951843262, "ms_per_req": 201.715140507139, "total_reqs": 29, "successful_reqs": 29, "reqs_per_sec": 3.384224700729303}, "observer": {"duration_sec": 8.481178045272827, "ms_per_req": 407.40778711107043, "total_reqs": 18, "successful_reqs": 18, "reqs_per_sec": 2.122346672115049}}
 
    By default, zaqar-bench is benchmarking Zaqar API version 2. To run
-   benchmark against other API versions use :option:`-api` parameter. For
+   benchmark against other API versions use ``-api`` parameter. For
    example:
 
    .. code-block:: console
@@ -158,10 +158,10 @@ Let's configure zaqar-bench too to use Keystone:
 
         .. code-block:: bash
 
-           export OS_AUTH_URL=http://<your keystone endpoint>/v2.0
-           export OS_USERNAME=<keystone user name>
-           export OS_PASSWORD=<the user's password>
-           export OS_PROJECT_NAME=<keystone project name for the user>
+           export OS_AUTH_URL="http://<your keystone endpoint>/v2.0"
+           export OS_USERNAME="<keystone user name>"
+           export OS_PASSWORD="<the user's password>"
+           export OS_PROJECT_NAME="<keystone project name for the user>"
 
      Reboot your computer or just run in the terminal where you will start
      zaqar-bench:

doc/source/subscription_confirm.rst

@@ -40,10 +40,12 @@ service first.
 The service could be started simply by the command::
 
     python zaqar/samples/zaqar/subscriber_service_sample.py
+
 The service's default port is 5678. If you want to use a new port, the command
 will be like::
 
     python zaqar/samples/zaqar/subscriber_service_sample.py new_port_number
+
 The service will not confirm the subscription automatically by default. If you
 want to do that, the command will be like::
 
@@ -80,6 +82,7 @@ service, the request is like::
     "Message": "You have chosen to subscribe to the queue: test",
     "Message_Type": "SubscriptionConfirmation"}
     10.229.47.217 - - [06/Jul/2016 11:35:56] "POST / HTTP/1.1" 200 -
+
 If you start the sample service with "--auto confirm", please go to step 6
 directly, because the step 5 will be done by the service automatically.
 
@@ -270,13 +273,16 @@ their own pages::
 
 User can place those pages in web server like Apache to access them by browser,
 so the external_confirmation_url will be like this::
+
     http://127.0.0.1:8080/subscriptionConfirmation.html
+
 For CORS, here used zaqar/samples/html/confirmation_web_service_sample.py
 be a simple web service for example, it will relay the confirmation request to
 Zaqar Server. So before Step 3, you should start the web service first.
 The service could be started simply by the command::
 
     python zaqar/samples/html/confirmation_web_service_sample.py
+
 The service's default port is 5678. If you want to use a new port, the command
 will be like::
 

setup.cfg

@@ -25,6 +25,7 @@ packages =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warning-is-error = 1
 
 [entry_points]
 console_scripts =
@@ -107,12 +108,6 @@ cover-inclusive = true
 ; detailed-errors = 1
 
 
-# NOTE(flaper87): Disable until the next pbr release to avoid breaking the gate
-# by unexpected errors. More info at:
-# http://lists.openstack.org/pipermail/openstack-dev/2016-June/097849.html
-# [pbr]
-# warnerrors = true
-
 [compile_catalog]
 directory = zaqar/locale
 domain = zaqar