From fb6cf77d97d05c7b0f50204f12c1905cda7552f4 Mon Sep 17 00:00:00 2001 From: Ruby Loo Date: Mon, 27 Oct 2014 21:37:22 +0000 Subject: [PATCH] Use docstrings for attributes in api/controllers We're using one double-quote for delimiting the strings that describe attributes. If the string spans more than one line, only the first line is used when sphinx generates the documentation. eg, for last_error, the generated documentation shows: Any error from the most recent (last) asynchronous transaction that instead of Any error from the most recent (last) asynchronous transaction that started but failed to finish. Using the docstring (three double-quotes) syntax addresses this. All the attributes in api/controllers were modified accordingly. This makes them consistent so that any additions/changes to these strings in the future will appear in the generated documentation as expected. (As opposed to only changing the ones that span more than one line.) [1] http://docs.openstack.org/developer/ironic/webapi/v1.html Change-Id: I84e4ba9c22827838ff31ba96a788cfc22609c8a5 --- ironic/api/controllers/base.py | 4 +- ironic/api/controllers/link.py | 6 +-- ironic/api/controllers/root.py | 16 +++--- ironic/api/controllers/v1/__init__.py | 14 +++--- ironic/api/controllers/v1/chassis.py | 14 +++--- ironic/api/controllers/v1/collection.py | 2 +- ironic/api/controllers/v1/driver.py | 8 +-- ironic/api/controllers/v1/node.py | 67 +++++++++++++------------ ironic/api/controllers/v1/port.py | 12 ++--- ironic/api/controllers/v1/state.py | 8 +-- 10 files changed, 77 insertions(+), 74 deletions(-) diff --git a/ironic/api/controllers/base.py b/ironic/api/controllers/base.py index 8a10ffbfc7..a132a339f0 100644 --- a/ironic/api/controllers/base.py +++ b/ironic/api/controllers/base.py @@ -21,10 +21,10 @@ from wsme import types as wtypes class APIBase(wtypes.Base): created_at = wsme.wsattr(datetime.datetime, readonly=True) - "The time in UTC at which the object is created" + """The time in UTC at which the object is created""" updated_at = wsme.wsattr(datetime.datetime, readonly=True) - "The time in UTC at which the object is updated" + """The time in UTC at which the object is updated""" def as_dict(self): """Render this object as a dict of its fields.""" diff --git a/ironic/api/controllers/link.py b/ironic/api/controllers/link.py index 46e9dcc86d..f980d0e4f0 100644 --- a/ironic/api/controllers/link.py +++ b/ironic/api/controllers/link.py @@ -35,13 +35,13 @@ class Link(base.APIBase): """A link representation.""" href = wtypes.text - "The url of a link." + """The url of a link.""" rel = wtypes.text - "The name of a link." + """The name of a link.""" type = wtypes.text - "Indicates the type of document/link." + """Indicates the type of document/link.""" @classmethod def make_link(cls, rel_name, url, resource, resource_args, diff --git a/ironic/api/controllers/root.py b/ironic/api/controllers/root.py index 1b88a34ee4..4934c1025c 100644 --- a/ironic/api/controllers/root.py +++ b/ironic/api/controllers/root.py @@ -30,10 +30,10 @@ class Version(base.APIBase): """An API version representation.""" id = wtypes.text - "The ID of the version, also acts as the release number" + """The ID of the version, also acts as the release number""" links = [link.Link] - "A Link that point to a specific version of the API" + """A Link that point to a specific version of the API""" @classmethod def convert(self, id): @@ -47,16 +47,16 @@ class Version(base.APIBase): class Root(base.APIBase): name = wtypes.text - "The name of the API" + """The name of the API""" description = wtypes.text - "Some information about this API" + """Some information about this API""" versions = [Version] - "Links to all the versions available in this API" + """Links to all the versions available in this API""" default_version = Version - "A link to the default version of the API" + """A link to the default version of the API""" @classmethod def convert(self): @@ -72,10 +72,10 @@ class Root(base.APIBase): class RootController(rest.RestController): _versions = ['v1'] - "All supported API versions" + """All supported API versions""" _default_version = 'v1' - "The default API version" + """The default API version""" v1 = v1.Controller() diff --git a/ironic/api/controllers/v1/__init__.py b/ironic/api/controllers/v1/__init__.py index 585130f72a..d3d26ce1b0 100644 --- a/ironic/api/controllers/v1/__init__.py +++ b/ironic/api/controllers/v1/__init__.py @@ -50,25 +50,25 @@ class V1(base.APIBase): """The representation of the version 1 of the API.""" id = wtypes.text - "The ID of the version, also acts as the release number" + """The ID of the version, also acts as the release number""" media_types = [MediaType] - "An array of supported media types for this version" + """An array of supported media types for this version""" links = [link.Link] - "Links that point to a specific URL for this version and documentation" + """Links that point to a specific URL for this version and documentation""" chassis = [link.Link] - "Links to the chassis resource" + """Links to the chassis resource""" nodes = [link.Link] - "Links to the nodes resource" + """Links to the nodes resource""" ports = [link.Link] - "Links to the ports resource" + """Links to the ports resource""" drivers = [link.Link] - "Links to the drivers resource" + """Links to the drivers resource""" @classmethod def convert(self): diff --git a/ironic/api/controllers/v1/chassis.py b/ironic/api/controllers/v1/chassis.py index 68b4a7534e..42fc48efb5 100644 --- a/ironic/api/controllers/v1/chassis.py +++ b/ironic/api/controllers/v1/chassis.py @@ -45,19 +45,19 @@ class Chassis(base.APIBase): """ uuid = types.uuid - "The UUID of the chassis" + """The UUID of the chassis""" description = wtypes.text - "The description of the chassis" + """The description of the chassis""" extra = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "The metadata of the chassis" + """The metadata of the chassis""" links = wsme.wsattr([link.Link], readonly=True) - "A list containing a self link and associated chassis links" + """A list containing a self link and associated chassis links""" nodes = wsme.wsattr([link.Link], readonly=True) - "Links to the collection of nodes contained in this chassis" + """Links to the collection of nodes contained in this chassis""" def __init__(self, **kwargs): self.fields = [] @@ -113,7 +113,7 @@ class ChassisCollection(collection.Collection): """API representation of a collection of chassis.""" chassis = [Chassis] - "A list containing chassis objects" + """A list containing chassis objects""" def __init__(self, **kwargs): self._type = 'chassis' @@ -139,7 +139,7 @@ class ChassisController(rest.RestController): """REST controller for Chassis.""" nodes = node.NodesController() - "Expose nodes as a sub-element of chassis" + """Expose nodes as a sub-element of chassis""" # Set the flag to indicate that the requests to this resource are # coming from a top-level resource diff --git a/ironic/api/controllers/v1/collection.py b/ironic/api/controllers/v1/collection.py index 6ec298791e..c60df9a3aa 100644 --- a/ironic/api/controllers/v1/collection.py +++ b/ironic/api/controllers/v1/collection.py @@ -23,7 +23,7 @@ from ironic.api.controllers import link class Collection(base.APIBase): next = wtypes.text - "A link to retrieve the next subset of the collection" + """A link to retrieve the next subset of the collection""" @property def collection(self): diff --git a/ironic/api/controllers/v1/driver.py b/ironic/api/controllers/v1/driver.py index 00c0139b9e..7405a0045f 100644 --- a/ironic/api/controllers/v1/driver.py +++ b/ironic/api/controllers/v1/driver.py @@ -40,13 +40,13 @@ class Driver(base.APIBase): """API representation of a driver.""" name = wtypes.text - "The name of the driver" + """The name of the driver""" hosts = [wtypes.text] - "A list of active conductors that support this driver" + """A list of active conductors that support this driver""" links = wsme.wsattr([link.Link], readonly=True) - "A list containing self and bookmark links" + """A list containing self and bookmark links""" @classmethod def convert_with_links(cls, name, hosts): @@ -75,7 +75,7 @@ class DriverList(base.APIBase): """API representation of a list of drivers.""" drivers = [Driver] - "A list containing drivers objects" + """A list containing drivers objects""" @classmethod def convert_with_links(cls, drivers): diff --git a/ironic/api/controllers/v1/node.py b/ironic/api/controllers/v1/node.py index 082f13fff8..7a75a797fe 100644 --- a/ironic/api/controllers/v1/node.py +++ b/ironic/api/controllers/v1/node.py @@ -137,19 +137,19 @@ class BootDeviceController(rest.RestController): class NodeManagementController(rest.RestController): boot_device = BootDeviceController() - "Expose boot_device as a sub-element of management" + """Expose boot_device as a sub-element of management""" class ConsoleInfo(base.APIBase): """API representation of the console information for a node.""" console_enabled = types.boolean - "The console state: if the console is enabled or not." + """The console state: if the console is enabled or not.""" console_info = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "The console information. It typically includes the url to access the" - "console and the type of the application that hosts the console." + """The console information. It typically includes the url to access the + console and the type of the application that hosts the console.""" @classmethod def sample(cls): @@ -242,7 +242,7 @@ class NodeStatesController(rest.RestController): } console = NodeConsoleController() - "Expose console as a sub-element of states" + """Expose console as a sub-element of states""" @wsme_pecan.wsexpose(NodeStates, types.uuid) def get(self, node_uuid): @@ -371,71 +371,73 @@ class Node(base.APIBase): self._chassis_uuid = wtypes.Unset uuid = types.uuid - "Unique UUID for this node" + """Unique UUID for this node""" instance_uuid = types.uuid - "The UUID of the instance in nova-compute" + """The UUID of the instance in nova-compute""" power_state = wsme.wsattr(wtypes.text, readonly=True) - "Represent the current (not transition) power state of the node" + """Represent the current (not transition) power state of the node""" target_power_state = wsme.wsattr(wtypes.text, readonly=True) - "The user modified desired power state of the node." + """The user modified desired power state of the node.""" last_error = wsme.wsattr(wtypes.text, readonly=True) - "Any error from the most recent (last) asynchronous transaction that" - "started but failed to finish." + """Any error from the most recent (last) asynchronous transaction that + started but failed to finish.""" provision_state = wsme.wsattr(wtypes.text, readonly=True) - "Represent the current (not transition) provision state of the node" + """Represent the current (not transition) provision state of the node""" reservation = wsme.wsattr(wtypes.text, readonly=True) - "The hostname of the conductor that holds an exclusive lock on the node." + """The hostname of the conductor that holds an exclusive lock on + the node.""" provision_updated_at = datetime.datetime - "The UTC date and time of the last provision state change" + """The UTC date and time of the last provision state change""" maintenance = types.boolean - "Indicates whether the node is in maintenance mode." + """Indicates whether the node is in maintenance mode.""" maintenance_reason = wsme.wsattr(wtypes.text, readonly=True) - "Indicates reason for putting a node in maintenance mode." + """Indicates reason for putting a node in maintenance mode.""" target_provision_state = wsme.wsattr(wtypes.text, readonly=True) - "The user modified desired provision state of the node." + """The user modified desired provision state of the node.""" console_enabled = types.boolean - "Indicates whether the console access is enabled or disabled on the node." + """Indicates whether the console access is enabled or disabled on + the node.""" instance_info = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "This node's instance info." + """This node's instance info.""" driver = wsme.wsattr(wtypes.text, mandatory=True) - "The driver responsible for controlling the node" + """The driver responsible for controlling the node""" driver_info = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "This node's driver configuration" + """This node's driver configuration""" extra = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "This node's meta data" + """This node's meta data""" # NOTE: properties should use a class to enforce required properties # current list: arch, cpus, disk, ram, image properties = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "The physical characteristics of this node" + """The physical characteristics of this node""" chassis_uuid = wsme.wsproperty(types.uuid, _get_chassis_uuid, _set_chassis_uuid) - "The UUID of the chassis this node belongs" + """The UUID of the chassis this node belongs""" links = wsme.wsattr([link.Link], readonly=True) - "A list containing a self link and associated node links" + """A list containing a self link and associated node links""" ports = wsme.wsattr([link.Link], readonly=True) - "Links to the collection of ports on this node" + """Links to the collection of ports on this node""" # NOTE(deva): "conductor_affinity" shouldn't be presented on the # API because it's an internal value. Don't add it here. @@ -517,7 +519,7 @@ class NodeCollection(collection.Collection): """API representation of a collection of nodes.""" nodes = [Node] - "A list containing nodes objects" + """A list containing nodes objects""" def __init__(self, **kwargs): self._type = 'nodes' @@ -607,19 +609,20 @@ class NodesController(rest.RestController): """REST controller for Nodes.""" states = NodeStatesController() - "Expose the state controller action as a sub-element of nodes" + """Expose the state controller action as a sub-element of nodes""" vendor_passthru = NodeVendorPassthruController() - "A resource used for vendors to expose a custom functionality in the API" + """A resource used for vendors to expose a custom functionality in + the API""" ports = port.PortsController() - "Expose ports as a sub-element of nodes" + """Expose ports as a sub-element of nodes""" management = NodeManagementController() - "Expose management as a sub-element of nodes" + """Expose management as a sub-element of nodes""" maintenance = NodeMaintenanceController() - "Expose maintenance as a sub-element of nodes" + """Expose maintenance as a sub-element of nodes""" # Set the flag to indicate that the requests to this resource are # coming from a top-level resource diff --git a/ironic/api/controllers/v1/port.py b/ironic/api/controllers/v1/port.py index 25da565c16..7ec1a3f821 100644 --- a/ironic/api/controllers/v1/port.py +++ b/ironic/api/controllers/v1/port.py @@ -72,20 +72,20 @@ class Port(base.APIBase): self._node_uuid = wtypes.Unset uuid = types.uuid - "Unique UUID for this port" + """Unique UUID for this port""" address = wsme.wsattr(types.macaddress, mandatory=True) - "MAC Address for this port" + """MAC Address for this port""" extra = {wtypes.text: types.MultiType(wtypes.text, six.integer_types)} - "This port's meta data" + """This port's meta data""" node_uuid = wsme.wsproperty(types.uuid, _get_node_uuid, _set_node_uuid, mandatory=True) - "The UUID of the node this port belongs to" + """The UUID of the node this port belongs to""" links = wsme.wsattr([link.Link], readonly=True) - "A list containing a self link and associated port links" + """A list containing a self link and associated port links""" def __init__(self, **kwargs): self.fields = [] @@ -145,7 +145,7 @@ class PortCollection(collection.Collection): """API representation of a collection of ports.""" ports = [Port] - "A list containing ports objects" + """A list containing ports objects""" def __init__(self, **kwargs): self._type = 'ports' diff --git a/ironic/api/controllers/v1/state.py b/ironic/api/controllers/v1/state.py index 2f85284ab0..ec5753f23b 100644 --- a/ironic/api/controllers/v1/state.py +++ b/ironic/api/controllers/v1/state.py @@ -22,13 +22,13 @@ from ironic.api.controllers import link class State(base.APIBase): current = wtypes.text - "The current state" + """The current state""" target = wtypes.text - "The user modified desired state" + """The user modified desired state""" available = [wtypes.text] - "A list of available states it is able to transition to" + """A list of available states it is able to transition to""" links = [link.Link] - "A list containing a self link and associated state links" + """A list containing a self link and associated state links"""