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)

1 files changed, 23 insertions, 18 deletions

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 [
             {