From 8d7c0d548dbf5b2548b3a283a13631e60f3f1d9e Mon Sep 17 00:00:00 2001 From: Eric Fried Date: Wed, 13 Jun 2018 10:46:16 -0500 Subject: [PATCH] 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 --- doc/source/user/usage.rst | 46 +++++++++++++++++++++------------------ os_vif/__init__.py | 16 +++++++------- os_vif/plugin.py | 18 +++++++-------- 3 files changed, 42 insertions(+), 38 deletions(-) diff --git a/doc/source/user/usage.rst b/doc/source/user/usage.rst index dcf691fb..bf642a52 100644 --- a/doc/source/user/usage.rst +++ b/doc/source/user/usage.rst @@ -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. diff --git a/os_vif/__init__.py b/os_vif/__init__.py index b05b9efc..1d51d0d6 100644 --- a/os_vif/__init__.py +++ b/os_vif/__init__.py @@ -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. diff --git a/os_vif/plugin.py b/os_vif/plugin.py index 5354e88b..8f89493c 100644 --- a/os_vif/plugin.py +++ b/os_vif/plugin.py @@ -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. """