Merge "doc: Fix arg specs and object types in docs"

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.

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.

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