Docs are generated incorrectly

When docs are generated with pbr command 'warnerrors = True'
there are many doc problems that are shown. This patch fixes
these problems.

Change-Id: Idb804ab924782b6d7d379494987bdba2acbce568
Closes-Bug: #1557235

doc/source/index.rst

@@ -23,7 +23,6 @@ In order to use the python api directly, you must first obtain an auth token and
 
 Python API Reference
 ~~~~~~~~~~~~~~~~~~~~
-
 .. toctree::
    :maxdepth: 2
 
@@ -31,6 +30,17 @@ Python API Reference
    ref/v1/index
    ref/v2/index
 
+.. toctree::
+   :maxdepth: 1
+
+   How to use the v2 API <apiv2>
+
+Command-line Tool Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. toctree::
+   :maxdepth: 1
+
+   man/glance
 
 Command-line Tool
 -----------------

glanceclient/v2/metadefs.py

@@ -102,7 +102,8 @@ class NamespaceController(object):
                        in a subsequent limited request.
         :param sort_key: The field to sort on (for example, 'created_at')
         :param sort_dir: The direction to sort ('asc' or 'desc')
-        :returns generator over list of Namespaces
+        :returns: generator over list of Namespaces
+
         """
 
         ori_validate_fun = self.model.validate
@@ -209,7 +210,7 @@ class ResourceTypeController(object):
     def list(self):
         """Retrieve a listing of available resource types.
 
-        :returns generator over list of resource_types
+        :returns: generator over list of resource_types
         """
 
         url = '/v2/metadefs/resource_types'
@@ -283,7 +284,7 @@ class PropertyController(object):
     def list(self, namespace, **kwargs):
         """Retrieve a listing of metadata properties.
 
-        :returns generator over list of objects
+        :returns: generator over list of objects
         """
         url = '/v2/metadefs/namespaces/{0}/properties'.format(namespace)
 
@@ -368,7 +369,7 @@ class ObjectController(object):
     def list(self, namespace, **kwargs):
         """Retrieve a listing of metadata objects.
 
-        :returns generator over list of objects
+        :returns: generator over list of objects
         """
         url = '/v2/metadefs/namespaces/{0}/objects'.format(namespace,)
         resp, body = self.http_client.get(url)
@@ -472,7 +473,7 @@ class TagController(object):
     def list(self, namespace, **kwargs):
         """Retrieve a listing of metadata tags.
 
-        :returns generator over list of tags.
+        :returns: generator over list of tags.
         """
         url = '/v2/metadefs/namespaces/{0}/tags'.format(namespace)
         resp, body = self.http_client.get(url)

glanceclient/v2/schemas.py

@@ -71,7 +71,7 @@ class SchemaProperty(object):
 def translate_schema_properties(schema_properties):
     """Parse the properties dictionary of a schema document.
 
-    :returns list of SchemaProperty objects
+    :returns: list of SchemaProperty objects
     """
     properties = []
     for (name, prop) in schema_properties.items():

glanceclient/v2/tasks.py

@@ -41,7 +41,8 @@ class Controller(object):
         """Retrieve a listing of Task objects.
 
         :param page_size: Number of tasks to request in each paginated request
-        :returns generator over list of Tasks
+        :returns: generator over list of Tasks
+
         """
         def paginate(url):
             resp, body = self.http_client.get(url)

tox.ini

@@ -21,6 +21,9 @@ commands = flake8
 [testenv:venv]
 commands = {posargs}
 
+[pbr]
+warnerror = True
+
 [testenv:functional]
 # See glanceclient/tests/functional/README.rst
 # for information on running the functional tests.
@@ -39,10 +42,11 @@ commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasen
 
 [flake8]
 # H233  Python 3.x incompatible use of print operator
+# H301  one import per line
 # H303  no wildcard import
 # H404  multi line docstring should start with a summary
 
-ignore = F403,F812,F821,H233,H303,H404
+ignore = F403,F812,F821,H233,H301,H303,H404
 show-source = True
 exclude = .venv*,.tox,dist,*egg,build,.git,doc,*openstack/common*,*lib/python*,.update-venv