doc: Fix arg specs and object types in docs
The usage doc stated that plug and unplug accept a single argument of type `os_vif.objects.VIF`, which isn't a thing, and then went on to give an example showing that they take two. The usage doc and the plug and unplug docstrings also listed various objects at the wrong paths (e.g. the `instance_info` param being of type `os_vif.objects.InstanceInfo`, which also isn't a thing). Fixed up the usage doc to list both arguments and correct the references in the sample code; and fixed the plug/unplug docstrings to list the proper paths to classes: os_vif.objects.vif.VIFBase and os_vif.objects.instance_info.InstanceInfo. Made everything in `single backticks` into a proper rst ``literal``. Change-Id: I400838bbe9663917fe2c64f52975b77a370405b4
This commit is contained in:
Eric Fried
Sean Mooney
parent
1f00350203
commit
8d7c0d548d
@ -2,8 +2,8 @@
|
||||
Usage
|
||||
=====
|
||||
|
||||
The interface to the `os_vif` library is very simple. To begin using the
|
||||
library, first call the `os_vif.initialize()` function. This will load all
|
||||
The interface to the ``os_vif`` library is very simple. To begin using the
|
||||
library, first call the ``os_vif.initialize()`` function. This will load all
|
||||
installed plugins and register the object model:
|
||||
|
||||
.. code-block:: python
|
||||
@ -12,9 +12,10 @@ installed plugins and register the object model:
|
||||
|
||||
os_vif.initialize()
|
||||
|
||||
Once the `os_vif` library is initialized, there are only two other library
|
||||
functions: `os_vif.plug()` and `os_vif.unplug()`. Both methods accept a single
|
||||
argument of type `os_vif.objects.VIF`:
|
||||
Once the ``os_vif`` library is initialized, there are only two other library
|
||||
functions: ``os_vif.plug()`` and ``os_vif.unplug()``. Both methods accept an
|
||||
argument of (a subclass of) type ``os_vif.objects.vif.VIFBase`` and an argument
|
||||
of type ``os_vif.objects.instance_info.InstanceInfo``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -22,31 +23,34 @@ argument of type `os_vif.objects.VIF`:
|
||||
|
||||
from nova import objects as nova_objects
|
||||
from os_vif import exception as vif_exc
|
||||
from os_vif import objects as vif_objects
|
||||
from os_vif import vnic_types
|
||||
from os_vif.objects import fields
|
||||
from os_vif.objects import instance_info
|
||||
from os_vif.objects import network
|
||||
from os_vif.objects import subnet
|
||||
from os_vif.objects import vif as vif_obj
|
||||
|
||||
instance_uuid = 'd7a730ca-3c28-49c3-8f26-4662b909fe8a'
|
||||
instance = nova_objects.Instance.get_by_uuid(instance_uuid)
|
||||
instance_info = vif_objects.InstanceInfo(
|
||||
instance_info = instance_info.InstanceInfo(
|
||||
uuid=instance.uuid,
|
||||
name=instance.name,
|
||||
project_id=instance.project_id)
|
||||
|
||||
subnet = vif_objects.Subnet(cidr='192.168.1.0/24')
|
||||
subnets = vif_objects.SubnetList([subnet])
|
||||
network = vif_objects.Network(label='tenantnet',
|
||||
subnets=subnets,
|
||||
multi_host=False,
|
||||
should_provide_vlan=False,
|
||||
should_provide_bridge=False)
|
||||
subnet = subnet.Subnet(cidr='192.168.1.0/24')
|
||||
subnets = subnet.SubnetList([subnet])
|
||||
network = network.Network(label='tenantnet',
|
||||
subnets=subnets,
|
||||
multi_host=False,
|
||||
should_provide_vlan=False,
|
||||
should_provide_bridge=False)
|
||||
|
||||
vif_uuid = uuid.uuid4()
|
||||
vif = vif_objects.VIFVHostUser(id=vif_uuid,
|
||||
address=None,
|
||||
network=network,
|
||||
plugin='vhostuser',
|
||||
path='/path/to/socket',
|
||||
mode=vif_objects.fields.VIFVHostUserMode.SERVER)
|
||||
vif = vif_obj.VIFVHostUser(id=vif_uuid,
|
||||
address=None,
|
||||
network=network,
|
||||
plugin='vhostuser',
|
||||
path='/path/to/socket',
|
||||
mode=fields.VIFVHostUserMode.SERVER)
|
||||
|
||||
# Now do the actual plug operations to connect the VIF to
|
||||
# the backing network interface.
|
||||
|
||||
@ -53,14 +53,14 @@ def plug(vif, instance_info):
|
||||
"""
|
||||
Given a model of a VIF, perform operations to plug the VIF properly.
|
||||
|
||||
:param vif: `os_vif.objects.VIF` object.
|
||||
:param instance_info: `os_vif.objects.InstanceInfo` object.
|
||||
:raises `exception.LibraryNotInitialized` if the user of the library
|
||||
did not call os_vif.initialize(**config) before trying to
|
||||
:param vif: Instance of a subclass of ``os_vif.objects.vif.VIFBase``.
|
||||
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo`` object.
|
||||
:raises ``exception.LibraryNotInitialized`` if the user of the library
|
||||
did not call ``os_vif.initialize(**config)`` before trying to
|
||||
plug a VIF.
|
||||
:raises `exception.NoMatchingPlugin` if there is no plugin for the
|
||||
:raises ``exception.NoMatchingPlugin`` if there is no plugin for the
|
||||
type of VIF supplied.
|
||||
:raises `exception.PlugException` if anything fails during unplug
|
||||
:raises ``exception.PlugException`` if anything fails during unplug
|
||||
operations.
|
||||
"""
|
||||
if _EXT_MANAGER is None:
|
||||
@ -86,8 +86,8 @@ def unplug(vif, instance_info):
|
||||
"""
|
||||
Given a model of a VIF, perform operations to unplug the VIF properly.
|
||||
|
||||
:param vif: `os_vif.objects.VIF` object.
|
||||
:param instance_info: `os_vif.objects.InstanceInfo` object.
|
||||
:param vif: Instance of a subclass of `os_vif.objects.vif.VIFBase`.
|
||||
:param instance_info: `os_vif.objects.instance_info.InstanceInfo` object.
|
||||
:raises `exception.LibraryNotInitialized` if the user of the library
|
||||
did not call os_vif.initialize(**config) before trying to
|
||||
plug a VIF.
|
||||
|
||||
@ -30,7 +30,7 @@ class PluginBase(object):
|
||||
"""
|
||||
Initialize the plugin object with the provided config
|
||||
|
||||
:param config: `oslo_config.ConfigOpts.GroupAttr` instance:
|
||||
:param config: ``oslo_config.ConfigOpts.GroupAttr`` instance:
|
||||
"""
|
||||
self.config = config
|
||||
|
||||
@ -40,7 +40,7 @@ class PluginBase(object):
|
||||
Return an object that describes the plugin's supported vif types and
|
||||
the earliest/latest known VIF object versions.
|
||||
|
||||
:returns: A `os_vif.objects.host_info.HostPluginInfo` instance
|
||||
:returns: A ``os_vif.objects.host_info.HostPluginInfo`` instance
|
||||
"""
|
||||
|
||||
@abc.abstractmethod
|
||||
@ -48,10 +48,10 @@ class PluginBase(object):
|
||||
"""
|
||||
Given a model of a VIF, perform operations to plug the VIF properly.
|
||||
|
||||
:param vif: `os_vif.objects.vif.VIFBase` object.
|
||||
:param instance_info: `os_vif.objects.instance_info.InstanceInfo`
|
||||
:param vif: ``os_vif.objects.vif.VIFBase`` object.
|
||||
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo``
|
||||
object.
|
||||
:raises: `processutils.ProcessExecutionError`. Plugins implementing
|
||||
:raises ``processutils.ProcessExecutionError``. Plugins implementing
|
||||
this method should let `processutils.ProcessExecutionError`
|
||||
bubble up.
|
||||
"""
|
||||
@ -61,11 +61,11 @@ class PluginBase(object):
|
||||
"""
|
||||
Given a model of a VIF, perform operations to unplug the VIF properly.
|
||||
|
||||
:param vif: `os_vif.objects.vif.VIFBase` object.
|
||||
:param instance_info: `os_vif.objects.instance_info.InstanceInfo`
|
||||
:param vif: ``os_vif.objects.vif.VIFBase`` object.
|
||||
:param instance_info: ``os_vif.objects.instance_info.InstanceInfo``
|
||||
object.
|
||||
:raises: `processutils.ProcessExecutionError`. Plugins implementing
|
||||
this method should let `processutils.ProcessExecutionError`
|
||||
:raises ``processutils.ProcessExecutionError``. Plugins implementing
|
||||
this method should let ``processutils.ProcessExecutionError``
|
||||
bubble up.
|
||||
"""
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user