Fix Sphinx Autodoc WARNING/ERROR in docs build

The docstrings here were all giving WARNINGs or ERRORs during the docs
build, and were generally making unappealing looking developer
documentation. I corrected the syntax and did what was neccessary to
make the build come out clean.

Change-Id: I74b00a7f125770b0468cff3bdf26d0d52cd054d7
(cherry picked from commit c0921cdff372ce1fd6df1c4ab4eb5463e2cba0e4)

4 files changed, 48 insertions, 38 deletions

diff --git a/ironic_python_agent/api/controllers/v1/base.py b/ironic_python_agent/api/controllers/v1/base.py
index 20af8964..769f819b 100644
--- a/ironic_python_agent/api/controllers/v1/base.py
+++ b/ironic_python_agent/api/controllers/v1/base.py
@@ -1,16 +1,16 @@
 # All Rights Reserved.
 #
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
 #
-#         http://www.apache.org/licenses/LICENSE-2.0
+# http://www.apache.org/licenses/LICENSE-2.0
 #
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
 
 import six
 from wsme import types as wtypes
@@ -45,7 +45,7 @@ class MultiType(wtypes.UserType):
 
     Used for validating that a value is an instance of one of the types.
 
-    :param *types: Variable-length list of types.
+    :param \*types: Variable-length list of types.
 
     """
     def __init__(self, *types):
diff --git a/ironic_python_agent/backoff.py b/ironic_python_agent/backoff.py
index b97f5dcb..0217a521 100644
--- a/ironic_python_agent/backoff.py
+++ b/ironic_python_agent/backoff.py
@@ -60,17 +60,20 @@ class BackOffLoopingCall(loopingcall.LoopingCallBase):
 
     :param initial_delay: delay before first running of function
     :param starting_interval: initial interval in seconds between calls to
-    function. When an error occurs and then a success, the interval is
-    returned to starting_interval
-    :param timeout: time in seconds before a LoopingCallTimeout is raised
-    The call will never take longer than timeout, but may quit before timeout
+                              function. When an error occurs and then a
+                              success, the interval is returned to
+                              starting_interval
+    :param timeout: time in seconds before a LoopingCallTimeout is raised.
+                    The call will never take longer than timeout, but may quit
+                    before timeout.
     :param max_interval: The maximum interval between calls during errors
     :param jitter: Used to vary when calls are actually run to avoid group of
-    calls all coming at the exact same time. Uses random.gauss(jitter,
-    0.1), with jitter as the mean for the distribution. If set below .5,
-    it can cause the calls to come more rapidly after each failure.
+                   calls all coming at the exact same time. Uses
+                   random.gauss(jitter, 0.1), with jitter as the mean for the
+                   distribution. If set below .5, it can cause the calls to
+                   come more rapidly after each failure.
     :raises: LoopingCallTimeout if time spent doing error retries would exceed
-    timeout.
+             timeout.
     """
 
     def start(self, initial_delay=None, starting_interval=1, timeout=300,
diff --git a/ironic_python_agent/extensions/clean.py b/ironic_python_agent/extensions/clean.py
index 30988fda..0659fb8b 100644
--- a/ironic_python_agent/extensions/clean.py
+++ b/ironic_python_agent/extensions/clean.py
@@ -40,12 +40,14 @@ class CleanExtension(base.BaseAgentExtension):
     @base.async_command('execute_clean_step')
     def execute_clean_step(self, step, node, ports, clean_version=None,
                            **kwargs):
-        """Execute a clean step
+        """Execute a clean step.
+
         :param step: A clean step with 'step', 'priority' and 'interface' keys
         :param node: A dict representation of a node
         :param ports: A dict representation of ports attached to node
         :param clean_version: The clean version as returned by
-            _get_current_clean_version() at the beginning of cleaning/zapping
+                              _get_current_clean_version() at the beginning
+                              of cleaning/zapping
         :returns: a CommandResult object with command_result set to whatever
             the step returns.
         """
diff --git a/ironic_python_agent/hardware.py b/ironic_python_agent/hardware.py
index 0875c66f..a7db004a 100644
--- a/ironic_python_agent/hardware.py
+++ b/ironic_python_agent/hardware.py
@@ -163,30 +163,35 @@ class HardwareManager(object):
     def get_clean_steps(self, node, ports):
         """Get a list of clean steps with priority.
 
-        Returns a list of dicts of the following form:
-        {'step': the HardwareManager function to call.
-         'priority': the order steps will be run in. Ironic will sort all the
-            clean steps from all the drivers, with the largest priority
-            step being run first. If priority is set to 0, the step will
-            not be run during cleaning, but may be run during zapping.
-         'reboot_requested': Whether the agent should request Ironic reboots
-            the node via the power driver after the operation completes.
-        }
-
-        Note: multiple hardware managers may return the same step name. The
-        priority of the step will be the largest priority of steps with
-        the same name. The steps will be called using
-        `hardware.dispatch_to_managers` and handled by the best suited
-        hardware manager. If you need a step to be executed by only your
-        hardware manager, ensure it has a unique step name.
+        Returns a list of steps. Each step is represeted by a dict::
+
+          {
+           'step': the HardwareManager function to call.
+           'priority': the order steps will be run in. Ironic will sort all
+                       the clean steps from all the drivers, with the largest
+                       priority step being run first. If priority is set to 0,
+                       the step will not be run during cleaning, but may be
+                       run during zapping.
+           'reboot_requested': Whether the agent should request Ironic reboots
+                               the node via the power driver after the
+                               operation completes.
+          }
+
+        If multiple hardware managers return the same step name, the priority
+        of the step will be the largest priority of steps with the same name.
+        The steps will be called using `hardware.dispatch_to_managers` and
+        handled by the best suited hardware manager. If you need a step to be
+        executed by only your hardware manager, ensure it has a unique step
+        name.
 
         `node` and `ports` can be used by other hardware managers to further
         determine if a clean step is supported for the node.
 
         :param node: Ironic node object
         :param ports: list of Ironic port objects
-        :return: a default list of decommission steps, as a list of
-        dictionaries
+        :return: a list of cleaning steps, where each step is described as a
+                 dict as defined above
+
         """
         return [
             {