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.

There are some invalid docstrings. These are cleaned up.

Change-Id: Ic6a028bab428b23255f36e5b2d64ee8d4d32978d

oslo_policy/policy.py

@@ -127,7 +127,8 @@ attributes obtained through a token:
     - domain_id or project_id (depending on the token scope)
     - list of roles held for the given token scope
 
-.. note:: Some resources which are exposed by the API do not support policy
+.. note::
+   Some resources which are exposed by the API do not support policy
    enforcement by user_id, and only support policy enforcement by project_id.
    Some global resources do not support policy enforcement by combination of
    user_id and project_id.
@@ -853,7 +854,8 @@ class DocumentedRuleDefault(RuleDefault):
     :param operations: List of dicts containing each api url and
         corresponding http request method.
 
-                       Example:
+        Example::
+
             operations=[{'path': '/foo', 'method': 'GET'},
                         {'path': '/some', 'method': 'POST'}]
     """

setup.cfg

@@ -23,8 +23,10 @@ packages =
     oslo_policy
 
 [pbr]
-warnerrors = true
 autodoc_tree_index_modules = True
+autodoc_tree_excludes =
+    setup.py
+    oslo_policy/tests/
 
 [entry_points]
 oslo.config.opts =
@@ -37,9 +39,10 @@ console_scripts =
     oslopolicy-list-redundant = oslo_policy.generator:list_redundant
 
 [build_sphinx]
+all-files = 1
+warning-is-error = 1
 source-dir = doc/source
 build-dir = doc/build
-all_files = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html