Fixing docstring formatting errors and warnings

Correcting numerous errors and warnings for doc generation.

Partial-Bug: #1486222
Change-Id: I6d6b20a433aa9965a1bafbd098e64b19886e5fca

8 files changed, 46 insertions, 35 deletions

diff --git a/horizon/forms/fields.py b/horizon/forms/fields.py
index 3ded97b1e..fab6b1061 100644
--- a/horizon/forms/fields.py
+++ b/horizon/forms/fields.py
@@ -147,30 +147,31 @@ 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' }
+            helpText = { 'Apple': 'This is a fruit',
+                      'Carrot': 'This is a vegetable' }
 
-        def get_title(data):
-            text = helpText.get(data, None)
-            if text:
-                return {'title': text}
-            else:
-                return {}
+            def get_title(data):
+                text = helpText.get(data, None)
+                if text:
+                    return {'title': text}
+                else:
+                    return {}
+
+            ....
+            ....
 
-        ....
-        ....
+            widget=forms.SelectWidget( attrs={'class': 'switchable',
+                                             'data-slug': 'source'},
+                                    transform_html_attrs=get_title )
 
-        widget=forms.SelectWidget( attrs={'class': 'switchable',
-                                          'data-slug': 'source'},
-                                   transform_html_attrs=get_title )
+            self.fields[<field name>].choices =
+                ([
+                    ('apple','Apple'),
+                    ('carrot','Carrot')
+                ])
 
-        self.fields[<field name>].choices =
-               ([
-                 ('apple','Apple'),
-                 ('carrot','Carrot')
-               ])
     """
     def __init__(self, attrs=None, choices=(), data_attrs=(), transform=None,
                  transform_html_attrs=None):
diff --git a/horizon/tables/base.py b/horizon/tables/base.py
index 229069951..51bdc2cd5 100644
--- a/horizon/tables/base.py
+++ b/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'
diff --git a/horizon/utils/file_discovery.py b/horizon/utils/file_discovery.py
index 128d4dbd2..00e0ff370 100644
--- a/horizon/utils/file_discovery.py
+++ b/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)]
diff --git a/openstack_dashboard/api/glance.py b/openstack_dashboard/api/glance.py
index a1420e640..425b15bad 100644
--- a/openstack_dashboard/api/glance.py
+++ b/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
-                 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.
+    :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.
 
-    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
@@ -250,9 +251,10 @@ def metadefs_namespace_list(request,
     :param filters: specifies addition fields to filter on such as
              resource_types.
     :returns A tuple of three values:
-             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).
+        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)
diff --git a/openstack_dashboard/api/network_base.py b/openstack_dashboard/api/network_base.py
index 7d740b209..b8e43494d 100644
--- a/openstack_dashboard/api/network_base.py
+++ b/openstack_dashboard/api/network_base.py
@@ -170,9 +170,9 @@ class SecurityGroupManager(object):
     * from_port: lower limit of allowed port range (inclusive)
     * to_port: upper limit of allowed port range (inclusive)
     * ip_range: remote IP CIDR (source for ingress, dest for egress).
-    The value should be a format of "{'cidr': <cidr>}"
+      The value should be a format of "{'cidr': <cidr>}"
     * group: remote security group. The value should be a format of
-    "{'name': <secgroup_name>}"
+      "{'name': <secgroup_name>}"
 
     """
 
diff --git a/openstack_dashboard/api/rest/neutron.py b/openstack_dashboard/api/rest/neutron.py
index 9150954c0..20d9f1ba8 100644
--- a/openstack_dashboard/api/rest/neutron.py
+++ b/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:
diff --git a/openstack_dashboard/dashboards/project/images/utils.py b/openstack_dashboard/dashboards/project/images/utils.py
index 07b781404..bb4fd45c6 100644
--- a/openstack_dashboard/dashboards/project/images/utils.py
+++ b/openstack_dashboard/dashboards/project/images/utils.py
@@ -86,8 +86,10 @@ 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
+        the list
+
     :return: list of (id, name) tuples
+
     """
     try:
         images = get_available_images(request, request.user.project_id)
diff --git a/openstack_dashboard/dashboards/project/instances/utils.py b/openstack_dashboard/dashboards/project/instances/utils.py
index c15beb67e..2db5d2e98 100644
--- a/openstack_dashboard/dashboards/project/instances/utils.py
+++ b/openstack_dashboard/dashboards/project/instances/utils.py
@@ -82,7 +82,7 @@ def network_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
+         the list
     :return: list of (id, name) tuples
     """
     tenant_id = request.user.tenant_id
@@ -114,7 +114,7 @@ def keypair_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
+        the list
     :return: list of (id, name) tuples
     """
     keypair_list = []
@@ -142,7 +142,7 @@ def flavor_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
+        the list
     :return: list of (id, name) tuples
     """
     flavors = flavor_list(request)