turn on warning-is-error for doc builds

Turn on the flag in setup.cfg.

Fix some formatting issues with a couple of docstrings.

Fix some mistakes in the rst files.

Suppress warnings from Sphinx extensions that used to be suppressed by
pbr with older versions of Sphinx.

Change-Id: I549292b5e22cf8ae0f54f878793a36f2cd3b8e6c
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

aodh/notifier/zaqar.py

@@ -40,17 +40,17 @@ class ZaqarAlarmNotifier(notifier.AlarmNotifier):
     to an existing Zaqar queue with a pre-signed URL.
 
     To create a new subscription in the service project, use a notification URL
-    of the form:
+    of the form::
 
         zaqar://?topic=example&subscriber=mailto%3A//test%40example.com&ttl=3600
 
-    Multiple subscribers are allowed. ``ttl` is the time to live of the
+    Multiple subscribers are allowed. ``ttl`` is the time to live of the
     subscription. The queue will be created automatically, in the service
     project, with a name based on the topic and the alarm ID.
 
     To use a pre-signed URL for an existing queue, use a notification URL with
     the scheme ``zaqar://`` and the pre-signing data from Zaqar in the query
-    string:
+    string::
 
         zaqar://?queue_name=example&project_id=foo&
                  paths=/messages&methods=POST&expires=1970-01-01T00:00Z&

doc/source/conf.py

@@ -321,3 +321,11 @@ epub_copyright = u'2012-2015, OpenStack'
 
 # Allow duplicate toc entries.
 #epub_tocdup = True
+
+# NOTE(dhellmann): pbr used to set this option but now that we are
+# using Sphinx>=1.6.2 it does not so we have to set it ourselves.
+suppress_warnings = [
+    'app.add_directive', 'app.add_role',
+    'app.add_generic_role', 'app.add_node',
+    'image.nonlocal_uri',
+]

doc/source/contributor/architecture.rst

@@ -4,8 +4,6 @@
  System Architecture
 =====================
 
-.. index::
-
 High-Level Architecture
 =======================
 

doc/source/contributor/configuration.rst

@@ -33,4 +33,4 @@ The following is a sample Aodh configuration for adaptation and use. It is
 auto-generated from Aodh when this documentation is built, and can also be
 viewed in `file form <_static/aodh.conf.sample>`_.
 
-.. literalinclude:: _static/aodh.conf.sample
+.. literalinclude:: ../_static/aodh.conf.sample

setup.cfg

@@ -126,6 +126,7 @@ tempest.test_plugins =
 all_files = 1
 build-dir = doc/build
 source-dir = doc/source
+warning-is-error = 1
 
 [pbr]
 warnerrors = true