openstack/ironic
Code Issues Proposed changes

Fix doc builds for ironic

Browse Source 
It seems that the wsme sphinx extension was concealing
issues in our doc builds, where formatting was not exactly
correct nor parsed as we would always expect as we have had
a tendency to fully document data structures as if we are
typing code.

Upon disabling the extension, the prior build failures due to
duplicate labels disappeared and other issues preventing the
docs from building successfully were raised.

It also seems that we never actually used the extension as
documented https://wsme.readthedocs.io/en/latest/document.html

$ grep -ir "wsme:root" ./ironic
$ grep -ir "wsme:type" ./ironic
$ grep -ir "wsme:attribute" ./ironic
$ grep -ir "wsme:service" ./ironic
$ grep -ir "autotype" ./ironic
./ironic/objects/fields.py:class FlexibleDictField(object_fields.AutoTypedField):
./ironic/objects/fields.py:class MACAddressField(object_fields.AutoTypedField):
$ grep -ir "autoattribute" ./ironic
$ grep -ir "autoservice" ./ironic
$ grep -ir "autofunction" ./ironic
$

Co-Authored-By: Dmitry Tantsur <dtantsur@redhat.com>
Change-Id: Ib5bbd9274a4098022fba69f0e4998485d2ee2396
Story: 2003020
Task:  23043
This commit is contained in:
Julia Kreger 2018-09-05 07:26:02 -07:00 committed by Dmitry Tantsur
parent c82749631c
commit 17c3de3413
14 changed files with 218 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/conf.py
View File

@ -30,7 +30,6 @@ extensions = ['sphinx.ext.viewcode',
'sphinxcontrib.pecanwsme.rest',
'sphinxcontrib.seqdiag',
'sphinxcontrib.apidoc',
'wsmeext.sphinxext',
'oslo_config.sphinxext',
'oslo_config.sphinxconfiggen',
'oslo_policy.sphinxext',

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

@ -62,7 +62,7 @@ def _emit_api_notification(context, obj, action, level, status, **kwargs):
`ironic.objects.fields.NotificationLevel.ALL`
:param status: Status to go in the EventType. One of
`ironic.objects.fields.NotificationStatus.ALL`
:param **kwargs: kwargs to use when creating the notification payload.
:param kwargs: kwargs to use when creating the notification payload.
"""
resource = obj.__class__.__name__.lower()
# value wsme.Unset can be passed from API representation of resource
@ -125,7 +125,7 @@ def emit_start_notification(context, obj, action, **kwargs):
:param context: request context.
:param obj: resource rpc object.
:param action: Action string to go in the EventType.
:param **kwargs: kwargs to use when creating the notification payload.
:param kwargs: kwargs to use when creating the notification payload.
"""
_emit_api_notification(context, obj, action,
fields.NotificationLevel.INFO,
@ -140,7 +140,7 @@ def handle_error_notification(context, obj, action, **kwargs):
:param context: request context.
:param obj: resource rpc object.
:param action: Action string to go in the EventType.
:param **kwargs: kwargs to use when creating the notification payload.
:param kwargs: kwargs to use when creating the notification payload.
"""
try:
yield
@ -158,7 +158,7 @@ def emit_end_notification(context, obj, action, **kwargs):
:param context: request context.
:param obj: resource rpc object.
:param action: Action string to go in the EventType.
:param **kwargs: kwargs to use when creating the notification payload.
:param kwargs: kwargs to use when creating the notification payload.
"""
_emit_api_notification(context, obj, action,
fields.NotificationLevel.INFO,

11
ironic/api/controllers/v1/utils.py
View File

@ -121,10 +121,13 @@ def apply_jsonpatch(doc, patch):
def get_patch_values(patch, path):
"""Get the patch values corresponding to the specified path.
If there are multiple values specified for the same path
(for example the patch is [{'op': 'add', 'path': '/name', 'value': 'abc'},
{'op': 'add', 'path': '/name', 'value': 'bca'}])
return all of them in a list (preserving order).
If there are multiple values specified for the same path, for example
::
[{'op': 'add', 'path': '/name', 'value': 'abc'},
{'op': 'add', 'path': '/name', 'value': 'bca'}]
return all of them in a list (preserving order)
:param patch: HTTP PATCH request body.
:param path: the path to get the patch values for.

9
ironic/common/cinder.py
View File

@ -185,7 +185,7 @@ def attach_volumes(task, volume_list, connector):
Some drivers support a 'multipath' boolean key,
although it is generally False. The 'host' key
is generally used for logging by drivers.
Example:
Example::
{
'wwpns': ['list','of','port','wwns'],
@ -214,8 +214,7 @@ def attach_volumes(task, volume_list, connector):
connection info for the node is already in the database,
'data' structure contains only basic info of volume ID in
cinder and ironic, so any logic based on that should
retrieve it from the database.
Example:
retrieve it from the database. Example::
[{
'driver_volume_type': 'fibre_channel'
@ -230,7 +229,7 @@ def attach_volumes(task, volume_list, connector):
{
'driver_volume_type': 'iscsi'
'data': {
'target_iqn': 'iqn.2010-10.org.openstack:volume-00000002',
'target_iqn': 'iqn.2010-10.org.openstack:volume-000002',
'target_portal': '127.0.0.0.1:3260',
'volume_id': '00000000-0000-0000-0000-000000000002',
'ironic_volume_id':
@ -353,7 +352,7 @@ def detach_volumes(task, volume_list, connector, allow_errors=False):
Some drivers support a 'multipath' boolean key,
although it is generally False. The 'host' key
is generally used for logging by drivers.
Example:
Example::
{
'wwpns': ['list','of','port','wwns']

9
ironic/common/images.py
View File

@ -47,7 +47,7 @@ def _create_root_fs(root_directory, files_info):
:param root_directory: the filesystem root directory.
:param files_info: A dict containing absolute path of file to be copied
-> relative path within the vfat image. For example,
-> relative path within the vfat image. For example::
{
'/absolute/path/to/file' -> 'relative/path/within/root'
...
@ -84,7 +84,8 @@ def create_vfat_image(output_file, files_info=None, parameters=None,
:param output_file: The path to the file where the fat fs image needs
to be created.
:param files_info: A dict containing absolute path of file to be copied
-> relative path within the vfat image. For example,
-> relative path within the vfat image. For example::
{
'/absolute/path/to/file' -> 'relative/path/within/root'
...
@ -93,8 +94,8 @@ def create_vfat_image(output_file, files_info=None, parameters=None,
:param parameters_file: The filename for the parameters file.
:param fs_size_kib: size of the vfat filesystem in KiB.
:raises: ImageCreationFailed, if image creation failed while doing any
of filesystem manipulation activities like creating dirs, mounting,
creating filesystem, copying files, etc.
of filesystem manipulation activities like creating dirs,
mounting, creating filesystem, copying files, etc.
"""
try:
ironic_utils.dd('/dev/zero', output_file, 'count=1',

16
ironic/common/neutron.py
View File

@ -355,8 +355,8 @@ def remove_neutron_ports(task, params):
def get_node_portmap(task):
"""Extract the switch port information for the node.
:param task: a task containing the Node object.
:returns: a dictionary in the form
The information is returned in the form of::
{
port.uuid: {
'switch_id': 'abc',
@ -364,6 +364,9 @@ def get_node_portmap(task):
'other_llc_key': 'val'
}
}
:param task: a task containing the Node object.
:returns: port information as a dict
"""
portmap = {}
@ -377,9 +380,8 @@ def get_node_portmap(task):
def get_local_group_information(task, portgroup):
"""Extract the portgroup information.
:param task: a task containing the Node object.
:param portgroup: Ironic portgroup object to extract data for.
:returns: a dictionary in the form:
The information is returned in the form of::
{
'id': portgroup.uuid,
'name': portgroup.name,
@ -389,6 +391,10 @@ def get_local_group_information(task, portgroup):
'bond_propertyB': 'valueB',
}
}
:param task: a task containing the Node object.
:param portgroup: Ironic portgroup object to extract data for.
:returns: port group information as a dict
"""
portgroup_properties = {}

22
ironic/drivers/modules/deploy_utils.py
View File

@ -367,16 +367,18 @@ def deploy_partition_image(
partition.
:param node_uuid: node's uuid. Used for logging.
:param preserve_ephemeral: If True, no filesystem is written to the
ephemeral block device, preserving whatever content it had (if the
partition table has not changed).
ephemeral block device, preserving whatever
content it had (if the partition table has
not changed).
:param configdrive: Optional. Base64 encoded Gzipped configdrive content
or configdrive HTTP URL.
:param boot_option: Can be "local" or "netboot".
"netboot" by default.
:param boot_mode: Can be "bios" or "uefi". "bios" by default.
:param disk_label: The disk label to be used when creating the
partition table. Valid values are: "msdos", "gpt" or None; If None
Ironic will figure it out according to the boot_mode parameter.
partition table. Valid values are: "msdos",
"gpt" or None; If None ironic will figure it
out according to the boot_mode parameter.
:param cpu_arch: Architecture of the node being deployed to.
:raises: InstanceDeployFailure if image virtual size is bigger than root
partition size.
@ -873,11 +875,11 @@ def prepare_inband_cleaning(task, manage_boot=True):
:param task: a TaskManager object containing the node
:param manage_boot: If this is set to True, this method calls the
'prepare_ramdisk' method of boot interface to boot the agent
ramdisk. If False, it skips preparing the boot agent ramdisk using
boot interface, and assumes that the environment is setup to
automatically boot agent ramdisk every time bare metal node is
rebooted.
'prepare_ramdisk' method of boot interface to boot the
agent ramdisk. If False, it skips preparing the boot
agent ramdisk using boot interface, and assumes that
the environment is setup to automatically boot agent
ramdisk every time bare metal node is rebooted.
:returns: states.CLEANWAIT to signify an asynchronous prepare.
:raises: NetworkError, NodeCleaningFailure if the previous cleaning ports
cannot be removed or if new cleaning ports cannot be created.
@ -1157,7 +1159,7 @@ def populate_storage_driver_internal_info(task):
"""Set node driver_internal_info for boot from volume parameters.
:param task: a TaskManager object containing the node.
:raises StorageError when a node has an iSCSI or FibreChannel boot volume
:raises: StorageError when a node has an iSCSI or FibreChannel boot volume
defined but is not capable to support it.
"""
node = task.node

45
ironic/drivers/modules/drac/bios.py
View File

@ -30,9 +30,8 @@ LOG = logging.getLogger(__name__)
def get_config(node):
"""Get the BIOS configuration.
:param node: an ironic node object.
:raises: DracOperationError on an error from python-dracclient.
:returns: a dictionary containing BIOS settings in the form of:
The BIOS settings look like::
{'EnumAttrib': {'name': 'EnumAttrib',
'current_value': 'Value',
'pending_value': 'New Value', # could also be None
@ -50,38 +49,46 @@ def get_config(node):
'pending_value': None,
'read_only': True,
'lower_bound': 0,
'upper_bound': 65535}
}
'upper_bound': 65535}}
:param node: an ironic node object.
:raises: DracOperationError on an error from python-dracclient.
:returns: a dictionary containing BIOS settings
The above values are only examples, of course. BIOS attributes exposed via
this API will always be either an enumerated attribute, a string attribute,
or an integer attribute. All attributes have the following parameters:
:name: is the name of the BIOS attribute.
:current_value: is the current value of the attribute.
:param name: is the name of the BIOS attribute.
:param current_value: is the current value of the attribute.
It will always be either an integer or a string.
:pending_value: is the new value that we want the attribute to have.
:param pending_value: is the new value that we want the attribute to have.
None means that there is no pending value.
:read_only: indicates whether this attribute can be changed. Trying to
change a read-only value will result in an error.
The read-only flag can change depending on other attributes.
A future version of this call may expose the dependencies
that indicate when that may happen.
:param read_only: indicates whether this attribute can be changed.
Trying to change a read-only value will result in
an error. The read-only flag can change depending
on other attributes.
A future version of this call may expose the
dependencies that indicate when that may happen.
Enumerable attributes also have the following parameters:
:possible_values: is an array of values it is permissible to set
:param possible_values: is an array of values it is permissible to set
the attribute to.
String attributes also have the following parameters:
:min_length: is the minimum length of the string.
:max_length: is the maximum length of the string.
:pcre_regex: is a PCRE compatible regular expression that the string
:param min_length: is the minimum length of the string.
:param max_length: is the maximum length of the string.
:param pcre_regex: is a PCRE compatible regular expression that the string
must match. It may be None if the string is read only
or if the string does not have to match any particular
regular expression.
Integer attributes also have the following parameters:
:lower_bound: is the minimum value the attribute can have.
:upper_bound: is the maximum value the attribute can have.
:param lower_bound: is the minimum value the attribute can have.
:param upper_bound: is the maximum value the attribute can have.
"""
client = drac_common.get_drac_client(node)

20
ironic/drivers/modules/ilo/common.py
View File

@ -546,11 +546,14 @@ def setup_vmedia(task, iso, ramdisk_options):
:param task: a TaskManager instance containing the node to act on.
:param iso: a bootable ISO image href to attach to. Should be either
of below:
* A Swift object - It should be of format 'swift:<object-name>'.
* A Swift object - It should be of format
``swift:<object-name>``.
It is assumed that the image object is present in
CONF.ilo.swift_ilo_container;
* A Glance image - It should be format 'glance://<glance-image-uuid>'
or just <glance-image-uuid>;
* A Glance image - It should be format
``glance://<glance-image-uuid>``
or just ``<glance-image-uuid>``;
* An HTTP URL.
:param ramdisk_options: the options to be passed to the ramdisk in virtual
media floppy.
@ -577,12 +580,15 @@ def setup_vmedia_for_boot(task, boot_iso, parameters=None):
:param task: a TaskManager instance containing the node to act on.
:param boot_iso: a bootable ISO image to attach to. Should be either
of below:
* A Swift object - It should be of format 'swift:<object-name>'.
* A Swift object - It should be of format
``swift:<object-name>``.
It is assumed that the image object is present in
CONF.ilo.swift_ilo_container;
* A Glance image - It should be format 'glance://<glance-image-uuid>'
or just <glance-image-uuid>;
* An HTTP(S) URL.
* A Glance image - It should be format
``glance://<glance-image-uuid>``
or just ``<glance-image-uuid>``;
* An HTTP URL.
:param parameters: the parameters to pass in the virtual floppy image
in a dictionary. This is optional.
:raises: ImageCreationFailed, if it failed while creating the floppy image.

37
ironic/drivers/modules/iscsi_deploy.py
View File

@ -216,14 +216,19 @@ def continue_deploy(task, **kwargs):
:raises: InvalidState if the event is not allowed by the associated
state machine.
:returns: a dictionary containing the following keys:
For partition image:
'root uuid': UUID of root partition
'efi system partition uuid': UUID of the uefi system partition
* 'root uuid': UUID of root partition
* 'efi system partition uuid': UUID of the uefi system partition
(if boot mode is uefi).
NOTE: If key exists but value is None, it means partition doesn't
exist.
.. note:: If key exists but value is None, it means partition
doesn't exist.
For whole disk image:
'disk identifier': ID of the disk to which image was deployed.
* 'disk identifier': ID of the disk to which image was deployed.
"""
node = task.node
@ -297,18 +302,24 @@ def do_agent_iscsi_deploy(task, agent_client):
:param task: a TaskManager object containing the node.
:param agent_client: an instance of agent_client.AgentClient
which will be used during iscsi deploy (for exposing node's
target disk via iSCSI, for install boot loader, etc).
which will be used during iscsi deploy
(for exposing node's target disk via iSCSI,
for install boot loader, etc).
:returns: a dictionary containing the following keys:
For partition image:
'root uuid': UUID of root partition
'efi system partition uuid': UUID of the uefi system partition
* 'root uuid': UUID of root partition
* 'efi system partition uuid': UUID of the uefi system partition
(if boot mode is uefi).
NOTE: If key exists but value is None, it means partition doesn't
exist.
.. note:: If key exists but value is None, it means partition
doesn't exist.
For whole disk image:
'disk identifier': ID of the disk to which image was deployed.
:raises: InstanceDeployFailure, if it encounters some error
* 'disk identifier': ID of the disk to which image was deployed.
:raises: InstanceDeployFailure if it encounters some error
during the deploy.
"""
node = task.node

6
ironic/drivers/modules/network/common.py
View File

@ -208,8 +208,8 @@ def plug_port_to_tenant_network(task, port_like_obj, client=None):
:param task: A TaskManager instance.
:param port_like_obj: port-like object to plug.
:param client: Neutron client instance.
:raises NetworkError: if failed to update Neutron port.
:raises VifNotAttached if tenant VIF is not associated with port_like_obj.
:raises: NetworkError if failed to update Neutron port.
:raises: VifNotAttached if tenant VIF is not associated with port_like_obj.
"""
node = task.node
@ -562,7 +562,7 @@ class NeutronVIFPortIDMixin(VIFPortIDMixin):
:param task: A TaskManager instance.
:param vif_id: A VIF ID to detach
:raises: VifNotAttached if VIF not attached.
:raises: NetworkError: if unbind Neutron port failed.
:raises: NetworkError if unbind Neutron port failed.
"""
# NOTE(mgoddard): Lookup the port first to check that the VIF is
# attached, and fail if not.

46
ironic/drivers/modules/oneview/common.py
View File

@ -136,7 +136,7 @@ def _get_ilo_access(remote_console):
The Remote Console url has the following format:
hplocons://addr=1.2.3.4&sessionkey=a79659e3b3b7c8209c901ac3509a6719
:param: remote_console: OneView Remote Console object with a
:param remote_console: OneView Remote Console object with a
remoteConsoleUrl
:returns: A tuple with the Host IP and Token to access ilo, for
example: ('1.2.3.4', 'a79659e3b3b7c8209c901ac3509a6719')
@ -177,13 +177,13 @@ def get_oneview_info(node):
:param: node: node object to get information from
:returns: a dictionary containing:
:server_hardware_uri: the uri of the server hardware in OneView
:server_hardware_type_uri: the uri of the server hardware type in
:param server_hardware_uri: the uri of the server hardware in OneView
:param server_hardware_type_uri: the uri of the server hardware type in
OneView
:enclosure_group_uri: the uri of the enclosure group in OneView
:param enclosure_group_uri: the uri of the enclosure group in OneView
:server_profile_template_uri: the uri of the server profile template in
OneView
:raises OneViewInvalidNodeParameter: if node capabilities are malformed
:raises: OneViewInvalidNodeParameter if node capabilities are malformed
"""
try:
@ -221,7 +221,7 @@ def validate_oneview_resources_compatibility(task):
serverProfileTemplateUri, enclosureGroupUri and node ports. If any
validation fails, the driver will raise an appropriate OneViewError.
:param: task: a TaskManager instance containing the node to act on.
:param task: a TaskManager instance containing the node to act on.
:raises: OneViewError if any validation fails.
"""
ports = task.ports
@ -305,7 +305,7 @@ def _get_server_hardware_mac_from_ilo(server_hardware):
"""Get the MAC of Server Hardware's iLO controller.
:param: server_hardware: a server hardware uuid or uri
:return: MAC of Server Hardware's iLO controller.
:returns: MAC of Server Hardware's iLO controller.
:raises: InvalidParameterValue if required iLO credentials are missing.
:raises: OneViewError if can't get mac from a server hardware via iLO or
if fails to get JSON object with the default path.
@ -334,8 +334,8 @@ def _get_server_hardware_mac_from_ilo(server_hardware):
def _get_server_hardware_mac(server_hardware):
"""Get the MAC address of the first PXE bootable port of an Ethernet port.
:param: server_hardware: OneView Server Hardware object.
:return: MAC of the first Ethernet and function 'a' port of the
:param server_hardware: OneView Server Hardware object.
:returns: MAC of the first Ethernet and function 'a' port of the
Server Hardware object.
:raises: OneViewError if there is no Ethernet port on the Server Hardware
or if there is no portMap on the Server Hardware requested.
@ -370,8 +370,8 @@ def _get_server_hardware_mac(server_hardware):
def _validate_node_server_profile_template(oneview_client, oneview_info):
"""Validate if the Server Profile Template is consistent.
:param: oneview_client: an instance of the HPE OneView client.
:param: oneview_info: the OneView related info in an Ironic node.
:param oneview_client: an instance of the HPE OneView client.
:param oneview_info: the OneView related info in an Ironic node.
:raises: OneViewError if the node's Server Profile Template is not
consistent.
"""
@ -393,8 +393,8 @@ def _validate_server_profile_template_server_hardware_type(
Validate if the Server Profile Template and the Server Hardware have the
same Server Hardware Type.
:param: server_profile_template: OneView Server Profile Template object.
:param: server_hardware: OneView Server Hardware object.
:param server_profile_template: OneView Server Profile Template object.
:param server_hardware: OneView Server Hardware object.
:raises: OneViewError if the Server Profile Template and the Server
Hardware does not have the same Server Hardware Type.
"""
@ -416,8 +416,8 @@ def _validate_server_profile_template_server_hardware_type(
def _validate_spt_enclosure_group(server_profile_template, server_hardware):
"""Validate Server Profile Template's Enclosure Group and Hardware's.
:param: server_profile_template: OneView Server Profile Template object.
:param: server_hardware: OneView Server Hardware object.
:param server_profile_template: OneView Server Profile Template object.
:param server_hardware: OneView Server Hardware object.
:raises: OneViewError if the Server Profile Template's Enclosure Group does
not match the Server Hardware's.
"""
@ -436,7 +436,7 @@ def _validate_spt_enclosure_group(server_profile_template, server_hardware):
def _validate_server_profile_template_manage_boot(server_profile_template):
"""Validate if the Server Profile Template allows to manage the boot order.
:param: server_profile_template: OneView Server Profile Template object.
:param server_profile_template: OneView Server Profile Template object.
:raises: OneViewError if the Server Profile Template does not allows to
manage the boot order.
"""
@ -472,8 +472,8 @@ def _validate_node_server_hardware_type(oneview_client, oneview_info):
def _validate_node_enclosure_group(oneview_client, oneview_info):
"""Validate if the node's Enclosure Group matches the Server Hardware's.
:param: oneview_client: an instance of the HPE OneView client.
:param: oneview_info: the OneView related info in an Ironic node.
:param oneview_client: an instance of the HPE OneView client.
:param oneview_info: the OneView related info in an Ironic node.
:raises: OneViewError if the node's enclosure group doesn't match the
Server Hardware's.
"""
@ -499,9 +499,9 @@ def _validate_node_port_mac_server_hardware(oneview_client,
oneview_info, ports):
"""Validate if a port matches the node's Server Hardware's MAC.
:param: oneview_client: an instance of the HPE OneView client.
:param: oneview_info: the OneView related info in an Ironic node.
:param: ports: a list of Ironic node's ports.
:param oneview_client: an instance of the HPE OneView client.
:param oneview_info: the OneView related info in an Ironic node.
:param ports: a list of Ironic node's ports.
:raises: OneViewError if there is no port with MAC address matching one
in OneView.
@ -539,8 +539,8 @@ def _validate_node_port_mac_server_hardware(oneview_client,
def _validate_server_profile_template_mac_type(oneview_client, oneview_info):
"""Validate if the node's Server Profile Template's MAC type is physical.
:param: oneview_client: an instance of the HPE OneView client.
:param: oneview_info: the OneView related info in an Ironic node.
:param oneview_client: an instance of the HPE OneView client.
:param oneview_info: the OneView related info in an Ironic node.
:raises: OneViewError if the node's Server Profile Template's MAC type is
not physical.
"""

4
tox.ini
View File

@ -87,9 +87,7 @@ deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
# FIXME(TheJulia): we need to add the -W flag back at some point to this command.
# See story https://storyboard.openstack.org/#!/story/2003020
commands = sphinx-build -b html doc/source doc/build/html
commands = sphinx-build -b html -W doc/source doc/build/html
[testenv:api-ref]
basepython = python3