turn on warning-is-error for documentation builds

Fix a bunch of formatting issues with docstrings to allow us to turn on
the flag that treats warnings as errors to avoid mal-formed
documentation in the future.

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

setup.cfg

@@ -45,7 +45,7 @@ openstack.database.v1 =
 all_files = 1
 source-dir = doc/source
 build-dir = doc/build
-#warning-is-error = 1
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html

troveclient/apiclient/auth.py

@@ -183,7 +183,7 @@ class BaseAuthPlugin(object):
         a request to authentication server.
 
         :param http_client: client object that needs authentication
-        :type http_client: HTTPClient
+        :type http_client: troveclient.client.HTTPClient
         :raises: AuthorizationFailure
         """
         self.sufficient_options()

troveclient/apiclient/base.py

@@ -75,8 +75,8 @@ class HookableMixin(object):
 
         :param cls: class that registers hooks
         :param hook_type: hook type, e.g., '__pre_parse_args__'
-        :param **args: args to be passed to every hook function
-        :param **kwargs: kwargs to be passed to every hook function
+        :param args: args to be passed to every hook function
+        :param kwargs: kwargs to be passed to every hook function
         """
         hook_funcs = cls._hooks_map.get(hook_type) or []
         for hook_func in hook_funcs:

troveclient/apiclient/client.py

@@ -46,6 +46,7 @@ class HTTPClient(object):
     """This client handles sending HTTP requests to OpenStack servers.
 
     Features:
+
     - share authentication information between several clients to different
       services (e.g., for compute and image clients);
     - reissue authentication request for expired tokens;
@@ -58,6 +59,7 @@ class HTTPClient(object):
       `http_client.identity` or `http_client.compute`;
     - log requests and responses in a format that is easy to copy-and-paste
       into terminal and send the same request with curl.
+
     """
 
     user_agent = "troveclient.apiclient"
@@ -151,7 +153,7 @@ class HTTPClient(object):
         :param method: method of HTTP request
         :param url: URL of HTTP request
         :param kwargs: any other parameter that can be passed to
-'            requests.Session.request (such as `headers`) or `json`
+             requests.Session.request (such as `headers`) or `json`
              that will be encoded as JSON and used as `data` argument
         """
         kwargs.setdefault("headers", kwargs.get("headers", {}))
@@ -206,7 +208,8 @@ class HTTPClient(object):
         :param method: method of HTTP request
         :param url: URL of HTTP request
         :param kwargs: any other parameter that can be passed to
-'            `HTTPClient.request`
+                       `HTTPClient.request`
+
         """
 
         filter_args = {

troveclient/utils.py

@@ -67,10 +67,12 @@ def add_arg(f, *args, **kwargs):
 def unauthenticated(f):
     """Adds 'unauthenticated' attribute to decorated function.
 
-    Usage:
+    Usage::
+
         @unauthenticated
         def mymethod(f):
             ...
+
     """
     f.unauthenticated = True
     return f
@@ -89,10 +91,12 @@ def isunauthenticated(f):
 def service_type(stype):
     """Adds 'service_type' attribute to decorated function.
 
-    Usage:
+    Usage::
+
         @service_type('database')
         def mymethod(f):
             ...
+
     """
     def inner(f):
         f.service_type = stype