Fix auto-generated REST API formatting

Fix an issue we have with the formatting of our auto-generated
REST API documentation. Sphinxcontrib-pecanwsme does not like
single-line method doc strings.

This patch adds some description of the RESTful parameters.

For methods that take no parameters (eg, get_all) it simply
converts the doc strings to multi-line, even though this does not
adhere to PEP257. This is a work-around for a bug.
  https://github.com/dreamhost/sphinxcontrib-pecanwsme/issues/8

Change-Id: I0fde3314bf2d5c3e109ec85626d3e509ffd53c7c

ironic/api/controllers/v1/chassis.py

@@ -139,7 +139,13 @@ class ChassisController(rest.RestController):
     @wsme_pecan.wsexpose(ChassisCollection, wtypes.text,
                          int, wtypes.text, wtypes.text)
     def get_all(self, marker=None, limit=None, sort_key='id', sort_dir='asc'):
-        """Retrieve a list of chassis."""
+        """Retrieve a list of chassis.
+
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         chassis = self._get_chassis(marker, limit, sort_key, sort_dir)
         return ChassisCollection.convert_with_links(chassis, limit,
                                                     sort_key=sort_key,
@@ -148,7 +154,13 @@ class ChassisController(rest.RestController):
     @wsme_pecan.wsexpose(ChassisCollection, wtypes.text, int,
                          wtypes.text, wtypes.text)
     def detail(self, marker=None, limit=None, sort_key='id', sort_dir='asc'):
-        """Retrieve a list of chassis with detail."""
+        """Retrieve a list of chassis with detail.
+
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         # /detail should only work agaist collections
         parent = pecan.request.path.split('/')[:-1][-1]
         if parent != "chassis":
@@ -164,13 +176,19 @@ class ChassisController(rest.RestController):
 
     @wsme_pecan.wsexpose(Chassis, wtypes.text)
     def get_one(self, uuid):
-        """Retrieve information about the given chassis."""
+        """Retrieve information about the given chassis.
+
+        :param uuid: UUID of a chassis.
+        """
         rpc_chassis = objects.Chassis.get_by_uuid(pecan.request.context, uuid)
         return Chassis.convert_with_links(rpc_chassis)
 
     @wsme_pecan.wsexpose(Chassis, body=Chassis)
     def post(self, chassis):
-        """Create a new chassis."""
+        """Create a new chassis.
+
+        :param chassis: a chassis within the request body.
+        """
         try:
             new_chassis = pecan.request.dbapi.create_chassis(chassis.as_dict())
         except Exception as e:
@@ -180,7 +198,11 @@ class ChassisController(rest.RestController):
 
     @wsme_pecan.wsexpose(Chassis, wtypes.text, body=[wtypes.text])
     def patch(self, uuid, patch):
-        """Update an existing chassis."""
+        """Update an existing chassis.
+
+        :param uuid: UUID of a chassis.
+        :param patch: a json PATCH document to apply to this chassis.
+        """
         chassis = objects.Chassis.get_by_uuid(pecan.request.context, uuid)
         chassis_dict = chassis.as_dict()
 
@@ -212,5 +234,8 @@ class ChassisController(rest.RestController):
 
     @wsme_pecan.wsexpose(None, wtypes.text, status_code=204)
     def delete(self, uuid):
-        """Delete a chassis."""
+        """Delete a chassis.
+
+        :param uuid: UUID of a chassis.
+        """
         pecan.request.dbapi.destroy_chassis(uuid)

ironic/api/controllers/v1/driver.py

@@ -63,7 +63,12 @@ class DriversController(rest.RestController):
 
     @wsme_pecan.wsexpose(DriverList)
     def get_all(self):
-        """Retrieve a list of drivers."""
+        """Retrieve a list of drivers.
+        """
+        # FIXME(deva): formatting of the auto-generated REST API docs
+        #              will break from a single-line doc string.
+        #              This is a result of a bug in sphinxcontrib-pecanwsme
+        # https://github.com/dreamhost/sphinxcontrib-pecanwsme/issues/8
         drivers = pecan.request.dbapi.list_active_conductor_drivers(
                                      interval=CONF.conductor.heartbeat_timeout)
         return DriverList.convert(drivers)

ironic/api/controllers/v1/node.py

@@ -79,7 +79,17 @@ class NodePowerStateController(rest.RestController):
     @wsme_pecan.wsexpose(NodePowerState, wtypes.text, wtypes.text,
                          status_code=202)
     def put(self, node_id, target):
-        """Set the power state of the machine."""
+        """Asynchronous request to set the power state of the node.
+
+        This will set the target power state of the node, and a background task
+        will begin which actually applies the state change. This call will
+        return a 202 (Accepted) indicating that the request is being processed.
+        The client should continue to GET the status of this node to observe
+        the status of the requested action.
+
+        :param node_id: UUID of the node.
+        :param target: Desired power state.
+        """
         node = objects.Node.get_by_uuid(pecan.request.context, node_id)
         if node.target_power_state is not None:
             raise wsme.exc.ClientSideError(_("Power operation for node %s is "
@@ -167,7 +177,10 @@ class NodeStatesController(rest.RestController):
     # GET nodes/<uuid>/state
     @wsme_pecan.wsexpose(NodeStates, wtypes.text)
     def get(self, node_id):
-        """List or update the state of a node."""
+        """List or update the state of a node.
+
+        :param node_id: UUID of a node.
+        """
         node = objects.Node.get_by_uuid(pecan.request.context, node_id)
         state = NodeStates.convert_with_links(node)
         return state
@@ -293,6 +306,12 @@ class NodeVendorPassthruController(rest.RestController):
                          body=wtypes.text,
                          status_code=202)
     def post(self, node_id, method, data):
+        """Call a vendor extension.
+
+        :param node_id: UUID of the node.
+        :param method: name of the method in vendor driver.
+        :param data: body of data to supply to the specified method.
+        """
         # Raise an exception if node is not found
         objects.Node.get_by_uuid(pecan.request.context, node_id)
 
@@ -392,7 +411,20 @@ class NodesController(rest.RestController):
                wtypes.text, wtypes.text, int, wtypes.text, wtypes.text)
     def get_all(self, chassis_id=None, instance_uuid=None, associated=None,
                 marker=None, limit=None, sort_key='id', sort_dir='asc'):
-        """Retrieve a list of nodes."""
+        """Retrieve a list of nodes.
+
+        :param chassis_id: Optional UUID of a chassis, to get only nodes for
+                           that chassis.
+        :param instance_uuid: Optional UUID of an instance, to find the node
+                              associated with that instance.
+        :param associated: Optional boolean whether to return a list of
+                           associated or unassociated nodes. May be combined
+                           with other parameters.
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         nodes = self._get_nodes(chassis_id, instance_uuid, associated, marker,
                                 limit, sort_key, sort_dir)
 
@@ -405,7 +437,20 @@ class NodesController(rest.RestController):
             wtypes.text, wtypes.text, int, wtypes.text, wtypes.text)
     def detail(self, chassis_id=None, instance_uuid=None, associated=None,
                marker=None, limit=None, sort_key='id', sort_dir='asc'):
-        """Retrieve a list of nodes with detail."""
+        """Retrieve a list of nodes with detail.
+
+        :param chassis_id: Optional UUID of a chassis, to get only nodes for
+                           that chassis.
+        :param instance_uuid: Optional UUID of an instance, to find the node
+                              associated with that instance.
+        :param associated: Optional boolean whether to return a list of
+                           associated or unassociated nodes. May be combined
+                           with other parameters.
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         # /detail should only work agaist collections
         parent = pecan.request.path.split('/')[:-1][-1]
         if parent != "nodes":
@@ -425,7 +470,10 @@ class NodesController(rest.RestController):
 
     @wsme_pecan.wsexpose(Node, wtypes.text)
     def get_one(self, uuid):
-        """Retrieve information about the given node."""
+        """Retrieve information about the given node.
+
+        :param uuid: UUID of a node.
+        """
         if self._from_chassis:
             raise exception.OperationNotPermitted
 
@@ -434,7 +482,10 @@ class NodesController(rest.RestController):
 
     @wsme_pecan.wsexpose(Node, body=Node)
     def post(self, node):
-        """Create a new node."""
+        """Create a new node.
+
+        :param node: a node within the request body.
+        """
         if self._from_chassis:
             raise exception.OperationNotPermitted
 
@@ -450,7 +501,11 @@ class NodesController(rest.RestController):
 
     @wsme_pecan.wsexpose(Node, wtypes.text, body=[wtypes.text])
     def patch(self, uuid, patch):
-        """Update an existing node."""
+        """Update an existing node.
+
+        :param uuid: UUID of a node.
+        :param patch: a json PATCH document to apply to this node.
+        """
         if self._from_chassis:
             raise exception.OperationNotPermitted
 
@@ -512,7 +567,10 @@ class NodesController(rest.RestController):
 
     @wsme_pecan.wsexpose(None, wtypes.text, status_code=204)
     def delete(self, node_id):
-        """Delete a node."""
+        """Delete a node.
+
+        :param node_id: UUID of the node.
+        """
         if self._from_chassis:
             raise exception.OperationNotPermitted
 

ironic/api/controllers/v1/port.py

@@ -176,7 +176,14 @@ class PortsController(rest.RestController):
                          wtypes.text, wtypes.text)
     def get_all(self, node_uuid=None, marker=None, limit=None,
                 sort_key='id', sort_dir='asc'):
-        """Retrieve a list of ports."""
+        """Retrieve a list of ports.
+
+        :param node_uuid: UUID of a node, to get only ports for that node.
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         ports = self._get_ports(node_uuid, marker, limit, sort_key, sort_dir)
         return PortCollection.convert_with_links(ports, limit,
                                                  sort_key=sort_key,
@@ -186,7 +193,14 @@ class PortsController(rest.RestController):
                          wtypes.text, wtypes.text)
     def detail(self, node_uuid=None, marker=None, limit=None,
                 sort_key='id', sort_dir='asc'):
-        """Retrieve a list of ports."""
+        """Retrieve a list of ports with detail.
+
+        :param node_uuid: UUID of a node, to get only ports for that node.
+        :param marker: pagination marker for large data sets.
+        :param limit: maximum number of resources to return in a single result.
+        :param sort_key: column to sort results by. Default: id.
+        :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
+        """
         # NOTE(lucasagomes): /detail should only work agaist collections
         parent = pecan.request.path.split('/')[:-1][-1]
         if parent != "ports":
@@ -202,7 +216,10 @@ class PortsController(rest.RestController):
 
     @wsme_pecan.wsexpose(Port, wtypes.text)
     def get_one(self, port_uuid):
-        """Retrieve information about the given port."""
+        """Retrieve information about the given port.
+
+        :param port_uuid: UUID of a port.
+        """
         if self._from_nodes:
             raise exception.OperationNotPermitted
 
@@ -211,7 +228,10 @@ class PortsController(rest.RestController):
 
     @wsme_pecan.wsexpose(Port, body=Port)
     def post(self, port):
-        """Create a new port."""
+        """Create a new port.
+
+        :param port: a port within the request body.
+        """
         if self._from_nodes:
             raise exception.OperationNotPermitted
 
@@ -225,7 +245,11 @@ class PortsController(rest.RestController):
     @wsme.validate(wtypes.text, [PortPatchType])
     @wsme_pecan.wsexpose(Port, wtypes.text, body=[PortPatchType])
     def patch(self, port_uuid, patch):
-        """Update an existing port."""
+        """Update an existing port.
+
+        :param port_uuid: UUID of a port.
+        :param patch: a json PATCH document to apply to this port.
+        """
         if self._from_nodes:
             raise exception.OperationNotPermitted
 
@@ -247,7 +271,10 @@ class PortsController(rest.RestController):
 
     @wsme_pecan.wsexpose(None, wtypes.text, status_code=204)
     def delete(self, port_id):
-        """Delete a port."""
+        """Delete a port.
+
+        :param port_id: UUID of a port.
+        """
         if self._from_nodes:
             raise exception.OperationNotPermitted