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
This commit is contained in:
Stephen Finucane 2019-02-21 12:01:27 +00:00
parent 8609f8a803
commit dfe319b386
4 changed files with 86 additions and 68 deletions

View File

@ -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',

View File

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

View File

@ -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 <https://netdevconf.org/1.2/session.html?or-gerlitz>`_ 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!

View File

@ -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 <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 <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 <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