Fixing docstring formatting errors and warnings

Correcting numerous errors and warnings for doc generation.

Partial-Bug: #1486222
Change-Id: I6d6b20a433aa9965a1bafbd098e64b19886e5fca

horizon/forms/fields.py

@@ -147,7 +147,7 @@ class SelectWidget(widgets.Select):
         for the option object. It returns a dictionary
         containing the html attributes and their values.
         For example, to define a title attribute for the
-        choices:
+        choices::
 
             helpText = { 'Apple': 'This is a fruit',
                       'Carrot': 'This is a vegetable' }
@@ -171,6 +171,7 @@ class SelectWidget(widgets.Select):
                     ('apple','Apple'),
                     ('carrot','Carrot')
                 ])
+
     """
     def __init__(self, attrs=None, choices=(), data_attrs=(), transform=None,
                  transform_html_attrs=None):

horizon/tables/base.py

@@ -163,7 +163,7 @@ class Column(html.HTMLElement):
        A callable to get the HTML attributes of a column cell depending
        on the data. For example, to add additional description or help
        information for data in a column cell (e.g. in Images panel, for the
-       column 'format'):
+       column 'format')::
 
             helpText = {
               'ARI':'Amazon Ramdisk Image'

horizon/utils/file_discovery.py

@@ -40,11 +40,14 @@ def sort_js_files(js_files):
     and spec files based on file extension.
 
     Output:
+
     * sources: source files for production.  The order of source files
       is significant and should be listed in the below order:
+
       - First, all the that defines the other application's angular module.
         Those files have extension of `.module.js`.  The order among them is
         not significant.
+
       - Followed by all other source code files.  The order among them
         is not significant.
 
@@ -53,6 +56,7 @@ def sort_js_files(js_files):
 
     * specs: spec files for testing.  They have extension of `.spec.js`.
       The order among them is not significant.
+
     """
     modules = [f for f in js_files if f.endswith(MODULE_EXT)]
     mocks = [f for f in js_files if f.endswith(MOCK_EXT)]

openstack_dashboard/api/glance.py

@@ -128,13 +128,13 @@ def image_update(request, image_id, **kwargs):
 def image_create(request, **kwargs):
     """Create image.
 
-    Keyword arguments:
-    copy_from -- URL from which Glance server should immediately copy
+    :param kwargs:
+        * copy_from: URL from which Glance server should immediately copy
             the data and store it in its configured image store.
-    data      -- Form data posted from client.
-    location  -- URL where the data for this image already resides.
+        * data: Form data posted from client.
+        * location: URL where the data for this image already resides.
 
-    In the case of 'copy_from' and 'location' the Glance server
+    In the case of 'copy_from' and 'location', the Glance server
     will give us a immediate response from create and handle the data
     asynchronously.
 
@@ -234,6 +234,7 @@ def metadefs_namespace_list(request,
                             marker=None,
                             paginate=False):
     """Retrieve a listing of Namespaces
+
     :param paginate: If true will perform pagination based on settings.
     :param marker: Specifies the namespace of the last-seen namespace.
              The typical pattern of limit and marker is to make an
@@ -253,6 +254,7 @@ def metadefs_namespace_list(request,
         1) Current page results
         2) A boolean of whether or not there are previous page(s).
         3) A boolean of whether or not there are more page(s).
+
     """
     limit = getattr(settings, 'API_RESULT_LIMIT', 1000)
     page_size = utils.get_page_size(request)

openstack_dashboard/api/rest/neutron.py

@@ -26,6 +26,7 @@ from openstack_dashboard.api.rest import urls
 @urls.register
 class Networks(generic.View):
     """API for Neutron Networks
+
     http://developer.openstack.org/api-ref-networking-v2.html
     """
     url_regex = r'neutron/networks/$'
@@ -44,6 +45,7 @@ class Networks(generic.View):
     @rest_utils.ajax(data_required=True)
     def post(self, request):
         """Create a network
+
         :param  admin_state_up (optional): The administrative state of the
                 network, which is up (true) or down (false).
         :param name (optional): The network name. A request body is optional:

openstack_dashboard/dashboards/project/images/utils.py

@@ -87,7 +87,9 @@ def image_field_data(request, include_empty_option=False):
     :param request: django http request object
     :param include_empty_option: flag to include a empty tuple in the front of
         the list
+
     :return: list of (id, name) tuples
+
     """
     try:
         images = get_available_images(request, request.user.project_id)