Fix docstring warnings

Partial-Bug: #1411719
Partial-Bug: #1486222

Change-Id: I2d649295e7425ab73f09f3a5d91076350bf7ed7a

horizon/exceptions.py

@@ -287,7 +287,7 @@ def handle(request, message=None, redirect=None, ignore=False,
        a redirect value may be passed to the error handler so users are
        returned to a different view than the one requested in addition to the
        error message.
-    #. RECOVERABLE: Generic API errors which generate a user-facing message
+    #. ``RECOVERABLE``: Generic API errors which generate a user-facing message
        but drop directly back to the regular code flow.
 
     All other exceptions bubble the stack as normal unless the ``ignore``

horizon/middleware/operation_log.py

@@ -27,14 +27,23 @@ LOG = logging.getLogger(__name__)
 class OperationLogMiddleware(object):
     """Middleware to output operation log.
 
-    This log can includes information below.
+    This log can includes information below:
-      <domain name>, <domain id>
+
-      <project name>, <project id>
+    - ``domain name``
-      <user name>, <user id>
+    - ``domain id``
-      <request scheme>, <referer url>, <request url>
+    - ``project name``
-      <message>, <method>, <http status>
+    - ``project id``
-      <request parameters>
+    - ``user name``
-    And log format is defined OPERATION_LOG_OPTIONS.
+    - ``user id``
+    - ``request scheme``
+    - ``referer url``
+    - ``request url``
+    - ``message``
+    - ``method``
+    - ``http status``
+    - ``request parameters``
+
+    and log format is defined OPERATION_LOG_OPTIONS.
     """
 
     @property

horizon/tables/base.py

@@ -899,7 +899,7 @@ class DataTableOptions(object):
 
         Boolean value to control the display of the "filter" search box
         in the table actions. By default it checks whether or not an instance
-        of :class:`.FilterAction` is in :attr:`.table_actions`.
+        of :class:`.FilterAction` is in ``table_actions``.
 
     .. attribute:: template
 

horizon/tables/views.py

@@ -284,10 +284,11 @@ class DataTableView(MultiTableView):
 
     def get_filters(self, filters=None, filters_map=None):
         """Converts a string given by the user into a valid api filter value.
+
         :filters: Default filter values.
-          {'filter1': filter_value, 'filter2': filter_value}
+            {'filter1': filter_value, 'filter2': filter_value}
         :filters_map: mapping between user input and valid api filter values.
-          {'filter_name':{_("true_value"):True, _("false_value"):False}
+            {'filter_name':{_("true_value"):True, _("false_value"):False}
         """
         filters = filters or {}
         filters_map = filters_map or {}

horizon/templatetags/horizon.py

@@ -218,9 +218,12 @@ def template_cache_age():
 
 @register.tag
 def minifyspace(parser, token):
-    """Removes whitespace including tab and newline characters. Do not use this
+    """Removes whitespace including tab and newline characters.
-    if you are using a <pre> tag
+
+    Do not use this if you are using a <pre> tag.
+
     Example usage::
+
         {% minifyspace %}
             <p>
                 <a title="foo"
@@ -229,8 +232,11 @@ def minifyspace(parser, token):
                 </a>
             </p>
         {% endminifyspace %}
+
     This example would return this HTML::
+
         <p><a title="foo" href="foo/">Foo</a></p>
+
     """
     nodelist = parser.parse(('endminifyspace',))
     parser.delete_first_token()

horizon/test/firefox_binary.py

@@ -31,10 +31,10 @@ class FirefoxBinary(firefox.firefox_binary.FirefoxBinary):
     cause hasn't been properly diagnosed yet but it's around:
 
     - getting a free port from the OS with
-    selenium.webdriver.common.utils free_port(),
+      selenium.webdriver.common.utils free_port(),
 
     - release the port immediately but record it in ff prefs so that ff
-    can listen on that port for the internal http server.
+      can listen on that port for the internal http server.
 
     It has been observed that this leads to hanging processes for
     'firefox -silent'.

horizon/test/test_hacking.py

@@ -25,23 +25,49 @@ class HackingTestCase(helpers.TestCase):
     strings to the check methods like the pep8/flake8 parser would. The parser
     loops over each line in the file and then passes the parameters to the
     check method. The parameter names in the check method dictate what type of
-    object is passed to the check method. The parameter types are::
+    object is passed to the check method. The parameter types are:
-        logical_line: A processed line with the following modifications:
+
-            - Multi-line statements converted to a single line.
+    logical_line
-            - Stripped left and right.
+        A processed line with the following modifications:
-            - Contents of strings replaced with "xxx" of same length.
+
-            - Comments removed.
+        - Multi-line statements converted to a single line.
-        physical_line: Raw line of text from the input file.
+        - Stripped left and right.
-        lines: a list of the raw lines from the input file
+        - Contents of strings replaced with "xxx" of same length.
-        tokens: the tokens that contribute to this logical line
+        - Comments removed.
-        line_number: line number in the input file
+
-        total_lines: number of lines in the input file
+    physical_line
-        blank_lines: blank lines before this one
+        Raw line of text from the input file.
-        indent_char: indentation character in this file (" " or "\t")
+
-        indent_level: indentation (with tabs expanded to multiples of 8)
+    lines
-        previous_indent_level: indentation on previous line
+        a list of the raw lines from the input file
-        previous_logical: previous logical line
+
-        filename: Path of the file being run through pep8
+    tokens
+        the tokens that contribute to this logical line
+
+    line_number
+        line number in the input file
+
+    total_lines
+        number of lines in the input file
+
+    blank_lines
+        blank lines before this one
+
+    indent_char
+        indentation character in this file (" " or "\t")
+
+    indent_level
+        indentation (with tabs expanded to multiples of 8)
+
+    previous_indent_level
+        indentation on previous line
+
+    previous_logical
+        previous logical line
+
+    filename
+        Path of the file being run through pep8
+
     When running a test on a check method the return will be False/None if
     there is no violation in the sample input. If there is an error a tuple is
     returned with a position in the line, and a message. So to check the result

horizon/utils/memoized.py

@@ -132,7 +132,7 @@ def memoized_with_request(request_func, request_index=0):
     request, and thus the memoizing will operate just on that part of the
     request that is relevant to the function being memoized.
 
-    short example:
+    short example::
 
         @memoized
         def _get_api_client(username, token_id, project_id, auth_url)

horizon/workflows/base.py

@@ -103,46 +103,51 @@ class Action(forms.Form):
 
     .. attribute:: name
 
-        The verbose name for this action. Defaults to the name of the class.
+       The verbose name for this action. Defaults to the name of the class.
 
     .. attribute:: slug
 
-        A semi-unique slug for this action. Defaults to the "slugified" name
+       A semi-unique slug for this action. Defaults to the "slugified" name
-        of the class.
+       of the class.
 
     .. attribute:: permissions
 
-        A list of permission names which this action requires in order to be
+       A list of permission names which this action requires in order to be
-        completed. Defaults to an empty list (``[]``).
+       completed. Defaults to an empty list (``[]``).
 
     .. attribute:: policy_rules
 
-        list of scope and rule tuples to do policy checks on, the
+       list of scope and rule tuples to do policy checks on, the
-        composition of which is (scope, rule)
+       composition of which is (scope, rule)
 
-            scope: service type managing the policy for action
+       * scope: service type managing the policy for action
-            rule: string representing the action to be checked
+       * rule: string representing the action to be checked
 
-            for a policy that requires a single rule check:
+       for a policy that requires a single rule check::
-                policy_rules should look like
+
-                    "(("compute", "compute:create_instance"),)"
+           policy_rules should look like
-            for a policy that requires multiple rule checks:
+               "(("compute", "compute:create_instance"),)"
-                rules should look like
+
-                    "(("identity", "identity:list_users"),
+       for a policy that requires multiple rule checks::
-                      ("identity", "identity:list_roles"))"
+
-                where two service-rule clauses are OR-ed.
+           rules should look like
+               "(("identity", "identity:list_users"),
+                 ("identity", "identity:list_roles"))"
+
+       where two service-rule clauses are OR-ed.
 
     .. attribute:: help_text
 
-        A string of simple help text to be displayed alongside the Action's
+       A string of simple help text to be displayed alongside the Action's
-        fields.
+       fields.
 
     .. attribute:: help_text_template
 
-        A path to a template which contains more complex help text to be
+       A path to a template which contains more complex help text to be
-        displayed alongside the Action's fields. In conjunction with
+       displayed alongside the Action's fields. In conjunction with
-        :meth:`~horizon.workflows.Action.get_help_text` method you can
+       :meth:`~horizon.workflows.Action.get_help_text` method you can
-        customize your help text template to display practically anything.
+       customize your help text template to display practically anything.
+
     """
 
     def __init__(self, request, context, *args, **kwargs):

openstack_dashboard/api/glance.py

@@ -233,39 +233,39 @@ def image_list_detailed(request, marker=None, sort_dir='desc',
     using the first object id on current page as the marker - restoring
     the original items ordering before sending them back to the UI.
 
-    .. param:: request
+    :param request:
 
         The request object coming from browser to be passed further into
         Glance service.
 
-    .. param:: marker
+    :param marker:
 
         The id of an object which defines a starting point of a query sent to
         Glance service.
 
-    .. param:: sort_dir
+    :param sort_dir:
 
         The direction by which the resulting image list throughout all pages
         (if pagination is enabled) will be sorted. Could be either 'asc'
         (ascending) or 'desc' (descending), defaults to 'desc'.
 
-    .. param:: sort_key
+    :param sort_key:
 
         The name of key by by which the resulting image list throughout all
         pages (if pagination is enabled) will be sorted. Defaults to
         'created_at'.
 
-    .. param:: filters
+    :param filters:
 
         A dictionary of filters passed as is to Glance service.
 
-    .. param:: paginate
+    :param paginate:
 
         Whether the pagination is enabled. If it is, then the number of
         entries on a single page of images table is limited to the specific
         number stored in browser cookies.
 
-    .. param:: reversed_order
+    :param reversed_order:
 
         Set this flag to True when it's necessary to get a reversed list of
         images from Glance (used for navigating the images list back in UI).

openstack_dashboard/api/rest/nova.py

@@ -190,7 +190,7 @@ class Limits(generic.View):
         request:
 
         :param reserved: Take into account the reserved limits. Reserved limits
-        may be instances in the rebuild process for example.
+            may be instances in the rebuild process for example.
 
         The result is an object with limits as properties.
         """

openstack_dashboard/templatetags/context_selection.py

@@ -117,9 +117,11 @@ def iframe_embed_settings(context):
 
 def get_project_name(project_id, projects):
     """Retrieves project name for given project id
+
     Args:
         projects: List of projects
         project_id: project id
+
     Returns: Project name or None if there is no match
     """
     for project in projects: