From dfe319b3860898526b956b6c32d38ad716519d57 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 21 Feb 2019 12:01:27 +0000 Subject: [PATCH] docs: Use sphinx.ext.autodoc for profile, datapath offload types This lets us keep all our docs in code where we can see them. Change-Id: I78ae5afbf9d17ddfde57208402ed3813492c28bc --- doc/source/conf.py | 1 + doc/source/reference/glossary.rst | 7 +++ doc/source/user/vif-types.rst | 73 +++++++------------------------ os_vif/objects/vif.py | 73 ++++++++++++++++++++++++++----- 4 files changed, 86 insertions(+), 68 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 12b3f182..a435056c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -16,6 +16,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ + 'sphinx.ext.todo', 'sphinx.ext.autodoc', 'openstackdocstheme', 'reno.sphinxext', diff --git a/doc/source/reference/glossary.rst b/doc/source/reference/glossary.rst index da1af644..05c73a31 100644 --- a/doc/source/reference/glossary.rst +++ b/doc/source/reference/glossary.rst @@ -14,6 +14,13 @@ Glossary __ http://docs.projectcalico.org + Fast Path + + When used, 6Wind's proprietary fast path technology behaves as a + transparent acceleration layer for traditional switches (:term:`Open + vSwitch`, :term:`Linux Bridge`) and for alternative networking mechanisms + (:term:`Calico`, Midonet). + Linux Bridge The native networking "backend" found in Linux. diff --git a/doc/source/user/vif-types.rst b/doc/source/user/vif-types.rst index c693d589..bf93df28 100644 --- a/doc/source/user/vif-types.rst +++ b/doc/source/user/vif-types.rst @@ -40,80 +40,39 @@ Each VIF instance can optionally be associated with a port profile object. This provides a set of metadata attributes that serve to identify the guest virtual interface to the host. Different types of host connectivity will require different port profile object metadata. Each port profile type is associated -with a versioned object, subclassing `VIFPortProfileBase`. +with a versioned object, subclassing :class:`VIFPortProfileBase`. -VIFPortProfileOpenVSwitch -------------------------- +.. autoclass:: VIFPortProfileBase -This profile provides the metadata required to associate a VIF with an Open -vSwitch host port. +.. autoclass:: VIFPortProfileOpenVSwitch -VIFPortProfile8021Qbg ---------------------- +.. autoclass:: VIFPortProfileFPOpenVSwitch -This profile provides the metadata required to associate a VIF with a VEPA host -device supporting the :term:`802.1Qbg` spec. +.. autoclass:: VIFPortProfileOVSRepresentor -VIFPortProfile8021Qbh ---------------------- +.. autoclass:: VIFPortProfileFPBridge -This profile provides the metadata required to associate a VIF with a VEPA host -device supporting the :term:`802.1Qbh` spec. +.. autoclass:: VIFPortProfileFPTap -VIFPortProfileFPOpenVSwitch ---------------------------- +.. autoclass:: VIFPortProfile8021Qbg -This profile provides the metadata required to associate a fast path -:term:`vhost-user` VIF with an :term:`Open vSwitch` port. +.. autoclass:: VIFPortProfile8021Qbh -VIFPortProfileOVSRepresentor ----------------------------- +.. autoclass:: VIFPortProfileK8sDPDK -This profile provides the metadata required to associate a VIF with a -:term:`VF` representor and :term:`Open vSwitch` port. If `representor_name` is -specified, it indicates a desire to rename the representor to the given name -on plugging. - -.. note:: This port profile is provided for backwards compatibility only. - -This interface has been superceded by the one provided by the -`DatapathOffloadRepresentor` class, which is now a field element of the -`VIFPortProfileBase` class. - -VIFPortProfileFPBridge ----------------------- - -This profile provides the metadata required to associate a fast path vhost-user -VIF with a :term:`Linux bridge` port. - -VIFPortProfileFPTap -------------------- - -This profile provides the metadata required to associate a fast path vhost-user -VIF with a Calico port. - -VIFPortProfileK8sDPDK ---------------------- - -This profile provides the metadata required to associate nested DPDK VIF with -a Kubernetes pod. Datapath Offload type object ============================ -Port profiles can be associated with a `datapath_offload` object. This +Port profiles can be associated with a ``datapath_offload`` object. This provides a set of metadata attributes that serve to identify the datapath offload parameters of a VIF. Each different type of datapath offload is -associated with a versioned object, subclassing `DatapathOffloadBase`. +associated with a versioned object, subclassing :class:`DatapathOffloadBase`. -DatapathOffloadRepresentor --------------------------- +.. autoclass:: DatapathOffloadBase + +.. autoclass:: DatapathOffloadRepresentor -This object provides the metadata required to associate a VIF with a -:term:`VF` representor conforming to the -`switchdev `_ kernel model. -If `representor_name` is specified, it indicates a desire to rename the -representor to the given name on plugging. VIF network objects =================== @@ -122,4 +81,4 @@ Each VIF instance is associated with a set of objects which describe the logical network that the guest will be plugged into. This information is again represented by a set of versioned objects -TODO :-( +.. todo:: Populate this! diff --git a/os_vif/objects/vif.py b/os_vif/objects/vif.py index 0aa8c2b1..0a71689f 100644 --- a/os_vif/objects/vif.py +++ b/os_vif/objects/vif.py @@ -268,7 +268,15 @@ class DatapathOffloadBase(osv_base.VersionedObject, @base.VersionedObjectRegistry.register class DatapathOffloadRepresentor(DatapathOffloadBase): - """Offload type for VF Representors conforming to the switchdev model.""" + """Offload type for VF Representors conforming to the switchdev model. + + This datapath offloads provides the metadata required to associate a VIF + with a :term:`VF` representor conforming to the `switchdev`_ kernel model. + If ``representor_name`` is specified, it indicates a desire to rename the + representor to the given name on plugging. + + .. _switchdev: https://netdevconf.org/1.2/session.html?or-gerlitz + """ # Version 1.0: Initial release VERSION = '1.0' @@ -285,7 +293,11 @@ class DatapathOffloadRepresentor(DatapathOffloadBase): @base.VersionedObjectRegistry.register class VIFPortProfileBase(osv_base.VersionedObject, base.ComparableVersionedObject): - """Base class for all types of port profile.""" + """Base class for all types of port profile. + + The base profile defines fields that are common to all types of profile. It + should not be instantiated itself - use a subclass instead. + """ # Version 1.0: Initial release # Version 1.1: Added 'datapath_offload' @@ -305,7 +317,11 @@ class VIFPortProfileBase(osv_base.VersionedObject, @base.VersionedObjectRegistry.register class VIFPortProfileOpenVSwitch(VIFPortProfileBase): - """Port profile info for Open vSwitch networks.""" + """Port profile info for Open vSwitch networks. + + This profile provides the metadata required to associate a VIF with an Open + vSwitch interface. + """ # Version 1.0: Initial release # Version 1.1: Added 'datapath_type' @@ -344,7 +360,11 @@ class VIFPortProfileOpenVSwitch(VIFPortProfileBase): @base.VersionedObjectRegistry.register class VIFPortProfileFPOpenVSwitch(VIFPortProfileOpenVSwitch): - """Port profile info for Open vSwitch networks using fastpath.""" + """Port profile info for Open vSwitch networks using fast path. + + This profile provides the metadata required to associate a :term:`fast + path ` VIF with an :term:`Open vSwitch` port. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileOpenVSwitch updated to 1.1 from 1.0 @@ -382,8 +402,19 @@ class VIFPortProfileFPOpenVSwitch(VIFPortProfileOpenVSwitch): class VIFPortProfileOVSRepresentor(VIFPortProfileOpenVSwitch): """Port profile info for OpenVSwitch networks using a representor. - This class is now frozen and retained for backwards compatibility. The - ``datapath_offload`` field in port profiles should be used instead. + This profile provides the metadata required to associate a VIF with a + :term:`VF` representor and :term:`Open vSwitch` port. If `representor_name` + is specified, it indicates a desire to rename the representor to the given + name on plugging. + + .. note:: + + This port profile is provided for backwards compatibility only. + + This interface has been superceded by the one provided by the + :class:`DatapathOffloadRepresentor` class, which is now a field element + of the :class:`VIFPortProfileBase` class. The ``datapath_offload`` + field in port profiles should be used instead. """ # Version 1.0: Initial release @@ -418,7 +449,11 @@ class VIFPortProfileOVSRepresentor(VIFPortProfileOpenVSwitch): @base.VersionedObjectRegistry.register class VIFPortProfileFPBridge(VIFPortProfileBase): - """Port profile info for LinuxBridge networks using fastpath.""" + """Port profile info for Linux Bridge networks using fast path. + + This profile provides the metadata required to associate a :term:`fast + path ` VIF with a :term:`Linux bridge` port. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileBase updated to 1.1 from 1.0 @@ -441,7 +476,11 @@ class VIFPortProfileFPBridge(VIFPortProfileBase): @base.VersionedObjectRegistry.register class VIFPortProfileFPTap(VIFPortProfileBase): - """Port profile info for Calico networks using fastpath.""" + """Port profile info for Calico networks using fast path. + + This profile provides the metadata required to associate a :term:`fast + path ` VIF with a :term:`Calico` port. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileBase updated to 1.1 from 1.0 @@ -464,7 +503,11 @@ class VIFPortProfileFPTap(VIFPortProfileBase): @base.VersionedObjectRegistry.register class VIFPortProfile8021Qbg(VIFPortProfileBase): - """Port profile info for VEPA 802.1qbg networks.""" + """Port profile info for VEPA 802.1qbg networks. + + This profile provides the metadata required to associate a VIF with a VEPA + host device supporting the :term:`802.1Qbg` spec. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileBase updated to 1.1 from 1.0 @@ -504,7 +547,11 @@ class VIFPortProfile8021Qbg(VIFPortProfileBase): @base.VersionedObjectRegistry.register class VIFPortProfile8021Qbh(VIFPortProfileBase): - """Port profile info for VEPA 802.1qbh networks.""" + """Port profile info for VEPA 802.1qbh networks. + + This profile provides the metadata required to associate a VIF with a VEPA + host device supporting the :term:`802.1Qbh` spec. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileBase updated to 1.1 from 1.0 @@ -530,7 +577,11 @@ class VIFPortProfile8021Qbh(VIFPortProfileBase): @base.VersionedObjectRegistry.register class VIFPortProfileK8sDPDK(VIFPortProfileBase): - """Port profile info for Kuryr-Kubernetes DPDK ports.""" + """Port profile info for Kuryr-Kubernetes DPDK ports. + + This profile provides the metadata required to associate nested DPDK VIF + with a Kubernetes pod. + """ # Version 1.0: Initial release # Version 1.1: VIFPortProfileBase updated to 1.1 from 1.0