docs: Use sphinx.ext.autodoc for VIF types

This lets us keep all our docs in code where we can see them.

Change-Id: Ibac3e94aa3d5018afbc331982e245951dc0ccd4b

doc/source/reference/glossary.rst

@@ -85,15 +85,21 @@ Glossary
 
    vhost
 
-     An alternative to :term:`virtio` that allows a userspace process to share
+     An alternative to :term:`virtio` that allows userspace guest processes to
-     *virtqueues* directly with the kernel, preventing the QEMU process from
+     share *virtqueues* directly with the kernel (or, more specifically, a
-     becoming a bottleneck.
+     kernel module) preventing the QEMU process from becoming a bottleneck.
 
    vhost-user
 
      A variation of :term:`vhost` that operates entirely in userspace. This
-     allows processes operating in userspace, such as virtual switches, to
+     allows userspace guest processes to share *virtqueues* with other processes
-     avoid the kernel entirely and maximize performance.
+     operating in userspace, such as virtual switches, avoiding the kernel
+     entirely and maximize performance.
+
+     When used, a guest exposes a UNIX socket for its control plane, allowing
+     the external userspace service to provide the backend data plane via a
+     mapped memory region. This process must implement the corresponding virtio
+     vhost protocol, such as :term:`virtio-net` for networking, on this socket.
 
      Refer to the `QEMU documentation`__ for more information.
 

doc/source/user/plugins/linux-bridge.rst

@@ -11,11 +11,9 @@ Supported VIF Types
 
 The Linux Bridge plugin provides support for the following VIF types:
 
-``VIFBridge``
+:mod:`~os_vif.objects.VIFBridge`
   Configuration where a guest is connected to a Linux bridge via a TAP device.
   This is the only supported configuration for this plugin.
 
-  Refer to :ref:`vif-bridge` for more information.
-
 For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
 that only the above VIF types are supported by this plugin.

doc/source/user/plugins/noop.rst

@@ -12,11 +12,9 @@ Supported VIF Types
 
 The no-op plugin provides support for the following VIF types:
 
-``VIFVHostUser``
+:mod:`~os_vif.objects.VIFVHostUser`
   Configuration where a guest exposes a UNIX socket for its control plane. This
   configuration is used with a userspace dataplane such as VPP or Snabb switch.
 
-  Refer to :ref:`vif-vhostuser` for more information.
-
 For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
 that only the above VIF types are supported by this plugin.

doc/source/user/plugins/ovs.rst

@@ -11,28 +11,24 @@ Supported VIF Types
 
 The Open vSwitch plugin provides support for the following VIF types:
 
-``VIFOpenVSwitch``
+:mod:`~os_vif.objects.VIFOpenVSwitch`
   Configuration where a guest is directly connected an Open vSwitch bridge.
 
-  Refer to :ref:`vif-openvswitch` for more information.
+:mod:`~os_vif.objects.VIFBridge`
-
-``VIFBridge``
   Configuration where a guest is connected to a Linux bridge via a TAP device,
   and that bridge is connected to the Open vSwitch bridge. This allows for the
   use of ``iptables`` rules for filtering traffic.
 
-  Refer to :ref:`vif-bridge` for more information.
+:mod:`~os_vif.objects.VIFVHostUser`
-
-``VIFVHostUser``
   Configuration where a guest exposes a UNIX socket for its control plane. This
   configuration is used with the `DPDK datapath of Open vSwitch`__.
 
-  Refer to :ref:`vif-vhostuser` for more information.
+  __ http://docs.openvswitch.org/en/latest/howto/dpdk/
 
-``VIFHostDevice``
+:mod:`~os_vif.objects.VIFHostDevice`
   Configuration where an :term:`SR-IOV` PCI device :term:`VF` is passed through
   to a guest. The ``hw-tc-offload`` feature should be enabled on the SR-IOV
-  :term:`PF` using ``ethtool``:
+  :term:`PF` using :command:`ethtool`:
 
   .. code-block:: shell
 
@@ -48,11 +44,7 @@ The Open vSwitch plugin provides support for the following VIF types:
       2.8. These add support for :term:`tc`-based hardware offloads for SR-IOV
       VFs and offloading of OVS datapath rules using tc, respectively.
 
-  Refer to :ref:`vif-hostdevice` for more information.
-
   .. versionadded:: 1.5.0
 
 For information on the VIF type objects, refer to :doc:`/user/vif-types`. Note
 that only the above VIF types are supported by this plugin.
-
-__ http://docs.openvswitch.org/en/latest/howto/dpdk/

doc/source/user/vif-types.rst

@@ -2,90 +2,36 @@
 VIF Types
 =========
 
-In os-vif, a VIF type refers to a particular approach for configuring the
+In *os-vif*, a VIF type refers to a particular approach for configuring the
 backend of a guest virtual network interface. There is a small, finite set of
 ways that a VIF backend can be configured for any given hypervisor and a
 limited amount of metadata is associated with each approach.
 
+
+.. py:module:: os_vif.objects.vif
+
 VIF objects
 ===========
 
-Each distinct type of VIF configuration is represented by a versioned object in
+Each distinct type of VIF configuration is represented by a versioned object,
-os-vif, subclassed from `os_vif.objects.VIFBase`. The `VIFBase` class defines
+subclassing :class:`VIFBase`.
-some fields that are common to all types of VIF, and provides an association to
-a versioned object describing the network the VIF is plugged into.
 
-.. _vif-generic:
+.. autoclass:: VIFBase
 
-VIFGeneric
+.. autoclass:: VIFGeneric
-----------
 
-This class provides a totally generic type of configuration, where the guest is
+.. autoclass:: VIFBridge
-simply associated with an arbitrary TAP device (or equivalent).  The way the
-TAP device is connected to the host network stack is explicitly left undefined
-and entirely up to the plugin to decide.
 
-.. _vif-bridge:
+.. autoclass:: VIFOpenVSwitch
 
-VIFBridge
+.. autoclass:: VIFDirect
----------
 
-This class provides a configuration where the guest is connected directly to an
+.. autoclass:: VIFVHostUser
-explicit host bridge device. This provides ethernet layer bridging, typically
-to the LAN.
 
-.. _vif-openvswitch:
+.. autoclass:: VIFDirect
 
-VIFOpenVSwitch
+.. autoclass:: VIFNestedDPDK
---------------
 
-This class provides a configuration where the guest is connected to an Open
-vSwitch port.
-
-.. _vif-direct:
-
-VIFDirect
----------
-
-This class provides a configuration where the guest is connected to a physical
-network device. The connection to the device may operate in one of a number of
-different modes, :term:`VEPA` (either :term:`802.1Qbg` or :term:`802.1Qbh`),
-passthrough (exclusive assignment of the host NIC) or bridge (ethernet layer
-bridging of traffic). The passthrough mode would be used when there is a
-network device which needs to have a MAC address or VLAN configuration. For
-passthrough of network devices without MAC/VLAN configuration, the
-`VIFHostDevice` should be used instead.
-
-.. _vif-vhostuser:
-
-VIFVHostUser
-------------
-
-This class provides another totally generic type of configuration, where the
-guest is exposing a UNIX socket for its control plane, allowing an external
-userspace service to provide the backend data plane via a mapped memory region.
-The process must implement the :term:`virtio-net` vhost protocol on this socket
-in whatever means is most suitable.
-
-.. _vif-hostdevice:
-
-VIFHostDevice
--------------
-
-This class provides a way to pass a physical device to the guest.  Either an
-entire physical device, or an SR-IOV PCI device virtual function, are
-permitted.
-
-.. _vif-nesteddpdk:
-
-VIFNestedDPDK
--------------
-
-This class provides a configuration, where kuryr-kuberentes is used to provide
-accelerated DPDK datapath for nested Kubernetes pods running inside the VM.
-Port is first attached to the virtual machine, bound to the userspace driver
-(e.g. uio_pci_generic, igb_uio or vfio-pci) and then consumed by Kubernetes
-pod via kuryr-kubernetes CNI plugin.
 
 VIF port profile objects
 ========================

os_vif/objects/vif.py

@@ -22,7 +22,12 @@ from os_vif.objects import fields as osv_fields
 
 @base.VersionedObjectRegistry.register
 class VIFBase(osv_base.VersionedObject, base.ComparableVersionedObject):
-    """Represents a virtual network interface."""
+    """Represents a virtual network interface.
+
+    The base VIF defines fields that are common to all types of VIF and
+    provides an association to the network the VIF is plugged into. It should
+    not be instantiated itself - use a subclass instead.
+    """
 
     # Version 1.0: Initial release
     VERSION = '1.0'
@@ -60,7 +65,8 @@ class VIFGeneric(VIFBase):
     """A generic-style VIF.
 
     Generic-style VIFs are unbound, floating TUN/TAP devices that should be
-    setup by the plugin, not the hypervisor.
+    setup by the plugin, not the hypervisor. The way the TAP device is
+    connected to the host network stack is explicitly left undefined.
 
     For libvirt drivers, this maps to type="ethernet" which just implies a bare
     TAP device with all setup delegated to the plugin.
@@ -79,8 +85,9 @@ class VIFGeneric(VIFBase):
 class VIFBridge(VIFBase):
     """A bridge-style VIF.
 
-    Bridge-style VIFs are bound to a linux bridge by the hypervisor. Other
+    Bridge-style VIFs are bound to a Linux host bridge by the hypervisor. This
-    devices may be bound to the same L2 virtual bridge.
+    provides Ethernet layer bridging, typically to the LAN. Other devices may
+    be bound to the same L2 virtual bridge.
 
     For libvirt drivers, this maps to type='bridge'.
     """
@@ -130,6 +137,15 @@ class VIFDirect(VIFBase):
     :class:`~os_vif.objects.vif.VIFHostDevice`, which allows the guest to
     directly connect to the VF.
 
+    The connection to the device may operate in one of a number of different
+    modes, :term:`VEPA` (either :term:`802.1Qbg` or :term:`802.1Qbh`),
+    passthrough (exclusive assignment of the host NIC) or bridge (ethernet
+    layer bridging of traffic). The passthrough mode would be used when there
+    is a network device which needs to have a MAC address or VLAN
+    configuration. For passthrough of network devices without MAC/VLAN
+    configuration, :class:`~os_vif.objects.vif.VIFHostDevice` should be used
+    instead.
+
     For libvirt drivers, this maps to type='direct'
     """
 
@@ -155,11 +171,11 @@ class VIFDirect(VIFBase):
 class VIFVHostUser(VIFBase):
     """A vhostuser-style VIF.
 
-    vhostuser-style VIFs utilize a userspace vhost backend, which allows
+    vhostuser-style VIFs utilize a :term:`userspace vhost <vhost-user>`
-    traffic to traverse between the guest and a host userspace application
+    backend, which allows traffic to traverse between the guest and a host
-    (commonly a virtual switch), bypassing the kernel network stack. Contrast
+    userspace application (commonly a virtual switch), bypassing the kernel
-    this with :class:`~os_vif.objects.vif.VIFBridge`, where all packets must be
+    network stack. Contrast this with :class:`~os_vif.objects.vif.VIFBridge`,
-    handled by the hypervisor.
+    where all packets must be handled by the hypervisor.
 
     For libvirt drivers, this maps to type='vhostuser'
     """
@@ -190,9 +206,10 @@ class VIFVHostUser(VIFBase):
 class VIFHostDevice(VIFBase):
     """A hostdev-style VIF.
 
-    Hostdev-style VIFs provide a guest with direct access to an SR-IOV Virtual
+    Hostdev-style VIFs provide a guest with direct access to an :term:`SR-IOV`
-    Function (VF). Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`,
+    :term:`Virtual Function` (VF) or an entire :term:`Physical Function` (PF).
-    which includes a software layer between the VF and the guest.
+    Contrast this with :class:`~ovs_vif.objects.vif.VIFDirect`, which includes
+    a software layer between the interface and the guest.
 
     For libvirt drivers, this maps to type='hostdev'
     """
@@ -216,9 +233,15 @@ class VIFHostDevice(VIFBase):
 
 @base.VersionedObjectRegistry.register
 class VIFNestedDPDK(VIFBase):
-    """TODO.
+    """A nested DPDK-style VIF.
 
-    For kuryr-kubernetes nested DPDK interfaces.
+    Nested DPDK-style VIFs are used by Kuryr-Kubernetes to provide accelerated
+    DPDK datapath for nested Kubernetes pods running inside the VM. The port
+    is first attached to the virtual machine, bound to the userspace driver
+    (e.g. ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci``) and then consumed
+    by Kubernetes pod via the kuryr-kubernetes CNI plugin.
+
+    This does not apply to libvirt drivers.
     """
 
     # Version 1.0: Initial release