openstack
/
ironic
Code Issues Proposed changes

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
This commit is contained in:
Ruby Loo 2014-10-27 21:37:22 +00:00
parent 9cee24e257
commit fb6cf77d97
10 changed files with 77 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ironic/api/controllers/base.py
View File

@ -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."""

6
ironic/api/controllers/link.py
View File

@ -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,

16
ironic/api/controllers/root.py
View File

@ -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()

14
ironic/api/controllers/v1/__init__.py
View File

@ -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):

14
ironic/api/controllers/v1/chassis.py
View File

@ -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

2
ironic/api/controllers/v1/collection.py
View File

@ -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):

8
ironic/api/controllers/v1/driver.py
View File

@ -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):

67
ironic/api/controllers/v1/node.py
View File

@ -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

12
ironic/api/controllers/v1/port.py
View File

@ -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'

8
ironic/api/controllers/v1/state.py
View File

@ -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"""