Sphinx-ify QuantumPluginBaseV2 docstrings

The quantum.quantum_plugin_base_v2 module had some good docstrings,
but there was no corresponding sphinx code that would generate
docs from them. There were also some syntax issues with the
sphinx markup in the docstrings.

This change adds sphinx directives so these docs will be auto-
generated. It also modifies the docstrings in the QuantumPluginBaseV2
methods so they are parsed by the Sphinx documentation generator
without any errors.

If this patch is accepted, a "Plugin API" link to these docs
will appear at

http://docs.openstack.org/developer/quantum/

Fixes bug 1186255

Change-Id: I96eddcc516d109766d7f4c52edd595748696b595

diff --git a/doc/source/devref/plugin-api.rst b/doc/source/devref/plugin-api.rst
new file mode 100644 (file)
index 0000000..fbf72ab
--- /dev/null
+++ b/doc/source/devref/plugin-api.rst
@@ -0,0 +1,7 @@
+Plugin API
+==========
+
+.. automodule:: quantum.quantum_plugin_base_v2
+
+.. autoclass:: QuantumPluginBaseV2
+    :members:

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 654768d5de2654468b43e6f7b68e8fcc4601555d..5539a78d4c512fad975a4b4f8ae097f7c7bd9322 100644 (file)
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -44,6 +44,7 @@ Development Documents
 .. toctree::
    :maxdepth: 1
 
+   devref/plugin-api
    devref/index
    devref/common
 

diff --git a/quantum/quantum_plugin_base_v2.py b/quantum/quantum_plugin_base_v2.py
index 35bbcf9971d0a31b2af91a2aa58518e590587ce2..43d21f1c64c79eeae6363d0577419cf7541f4134 100644 (file)
--- a/quantum/quantum_plugin_base_v2.py
+++ b/quantum/quantum_plugin_base_v2.py
@@ -17,7 +17,7 @@
 """
 v2 Quantum Plug-in API specification.
 
-QuantumPluginBase provides the definition of minimum set of
+:class:`QuantumPluginBaseV2` provides the definition of minimum set of
 methods that needs to be implemented by a v2 Quantum Plug-in.
 """
 
@@ -36,10 +36,12 @@ class QuantumPluginBaseV2(object):
 
         Create a subnet, which represents a range of IP addresses
         that can be allocated to devices
-        : param context: quantum api request context
-        : param subnet: dictionary describing the subnet, with keys
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.  All keys will be populated.
+
+        :param context: quantum api request context
+        :param subnet: dictionary describing the subnet, with keys
+                       as listed in the  :obj:`RESOURCE_ATTRIBUTE_MAP` object
+                       in :file:`quantum/api/v2/attributes.py`.  All keys will
+                       be populated.
         """
         pass
 
@@ -47,12 +49,13 @@ class QuantumPluginBaseV2(object):
     def update_subnet(self, context, id, subnet):
         """Update values of a subnet.
 
-        : param context: quantum api request context
-        : param id: UUID representing the subnet to update.
-        : param subnet: dictionary with keys indicating fields to update.
-            valid keys are those that have a value of True for 'allow_put'
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.
+        :param context: quantum api request context
+        :param id: UUID representing the subnet to update.
+        :param subnet: dictionary with keys indicating fields to update.
+                       valid keys are those that have a value of True for
+                       'allow_put' as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`.
         """
         pass
 
@@ -60,12 +63,13 @@ class QuantumPluginBaseV2(object):
     def get_subnet(self, context, id, fields=None):
         """Retrieve a subnet.
 
-        : param context: quantum api request context
-        : param id: UUID representing the subnet to fetch.
-        : param fields: a list of strings that are valid keys in a
-            subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+        :param context: quantum api request context
+        :param id: UUID representing the subnet to fetch.
+        :param fields: a list of strings that are valid keys in a
+                       subnet dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -77,18 +81,21 @@ class QuantumPluginBaseV2(object):
         The contents of the list depends on
         the identity of the user making the request (as indicated by the
         context) as well as any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a subnet as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
-        : param fields: a list of strings that are valid keys in a
-            subnet dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a subnet as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP`
+                        object in :file:`quantum/api/v2/attributes.py`.
+                        Values in this dictiontary are an iterable containing
+                        values that will be used for an exact match comparison
+                        for that value.  Each result returned by this
+                        function will have matched one of the values for each
+                        key in filters.
+        :param fields: a list of strings that are valid keys in a
+                       subnet dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -98,17 +105,19 @@ class QuantumPluginBaseV2(object):
         The result depends on the identity of
         the user making the request (as indicated by the context) as well as
         any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a network as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
 
-        NOTE: this method is optional, as it was not part of the originally
-              defined plugin API.
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a network as listed in the
+                        :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                        :file:`quantum/api/v2/attributes.py`.  Values in this
+                        dictiontary are an iterable containing values that
+                        will be used for an exact match comparison for that
+                        value.  Each result returned by this function will
+                        have matched one of the values for each key in filters.
+
+        .. note:: this method is optional, as it was not part of the originally
+                  defined plugin API.
         """
         raise exceptions.NotImplementedError()
 
@@ -116,8 +125,8 @@ class QuantumPluginBaseV2(object):
     def delete_subnet(self, context, id):
         """Delete a subnet.
 
-        : param context: quantum api request context
-        : param id: UUID representing the subnet to delete.
+        :param context: quantum api request context
+        :param id: UUID representing the subnet to delete.
         """
         pass
 
@@ -127,10 +136,13 @@ class QuantumPluginBaseV2(object):
 
         Create a network, which represents an L2 network segment which
         can have a set of subnets and ports associated with it.
-        : param context: quantum api request context
-        : param network: dictionary describing the network, with keys
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.  All keys will be populated.
+
+        :param context: quantum api request context
+        :param network: dictionary describing the network, with keys
+                        as listed in the  :obj:`RESOURCE_ATTRIBUTE_MAP` object
+                        in :file:`quantum/api/v2/attributes.py`.  All keys will
+                        be populated.
+
         """
         pass
 
@@ -138,12 +150,13 @@ class QuantumPluginBaseV2(object):
     def update_network(self, context, id, network):
         """Update values of a network.
 
-        : param context: quantum api request context
-        : param id: UUID representing the network to update.
-        : param network: dictionary with keys indicating fields to update.
-            valid keys are those that have a value of True for 'allow_put'
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.
+        :param context: quantum api request context
+        :param id: UUID representing the network to update.
+        :param network: dictionary with keys indicating fields to update.
+                        valid keys are those that have a value of True for
+                        'allow_put' as listed in the
+                        :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                        :file:`quantum/api/v2/attributes.py`.
         """
         pass
 
@@ -151,12 +164,13 @@ class QuantumPluginBaseV2(object):
     def get_network(self, context, id, fields=None):
         """Retrieve a network.
 
-        : param context: quantum api request context
-        : param id: UUID representing the network to fetch.
-        : param fields: a list of strings that are valid keys in a
-            network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+        :param context: quantum api request context
+        :param id: UUID representing the network to fetch.
+        :param fields: a list of strings that are valid keys in a
+                       network dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -168,18 +182,21 @@ class QuantumPluginBaseV2(object):
         The contents of the list depends on
         the identity of the user making the request (as indicated by the
         context) as well as any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a network as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
-        : param fields: a list of strings that are valid keys in a
-            network dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a network as listed in the
+                        :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                        :file:`quantum/api/v2/attributes.py`.  Values in this
+                        dictiontary are an iterable containing values that will
+                        be used for an exact match comparison for that value.
+                        Each result returned by this function will have matched
+                        one of the values for each key in filters.
+        :param fields: a list of strings that are valid keys in a
+                       network dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -189,14 +206,16 @@ class QuantumPluginBaseV2(object):
         The result depends on the identity
         of the user making the request (as indicated by the context) as well
         as any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a network as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
+
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a network as listed in the
+                        :obj:`RESOURCE_ATTRIBUTE_MAP` object
+                        in :file:`quantum/api/v2/attributes.py`. Values in
+                        this dictiontary are an iterable containing values that
+                        will be used for an exact match comparison for that
+                        value.  Each result returned by this function will have
+                        matched one of the values for each key in filters.
 
         NOTE: this method is optional, as it was not part of the originally
               defined plugin API.
@@ -207,8 +226,8 @@ class QuantumPluginBaseV2(object):
     def delete_network(self, context, id):
         """Delete a network.
 
-        : param context: quantum api request context
-        : param id: UUID representing the network to delete.
+        :param context: quantum api request context
+        :param id: UUID representing the network to delete.
         """
         pass
 
@@ -218,10 +237,12 @@ class QuantumPluginBaseV2(object):
 
         Create a port, which is a connection point of a device (e.g., a VM
         NIC) to attach to a L2 Quantum network.
-        : param context: quantum api request context
-        : param port: dictionary describing the port, with keys
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.  All keys will be populated.
+
+        :param context: quantum api request context
+        :param port: dictionary describing the port, with keys as listed in the
+                     :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                     :file:`quantum/api/v2/attributes.py`.  All keys will be
+                     populated.
         """
         pass
 
@@ -229,12 +250,12 @@ class QuantumPluginBaseV2(object):
     def update_port(self, context, id, port):
         """Update values of a port.
 
-        : param context: quantum api request context
-        : param id: UUID representing the port to update.
-        : param port: dictionary with keys indicating fields to update.
-            valid keys are those that have a value of True for 'allow_put'
-            as listed in the RESOURCE_ATTRIBUTE_MAP object in
-            quantum/api/v2/attributes.py.
+        :param context: quantum api request context
+        :param id: UUID representing the port to update.
+        :param port: dictionary with keys indicating fields to update.
+                     valid keys are those that have a value of True for
+                     'allow_put' as listed in the :obj:`RESOURCE_ATTRIBUTE_MAP`
+                     object in :file:`quantum/api/v2/attributes.py`.
         """
         pass
 
@@ -242,12 +263,13 @@ class QuantumPluginBaseV2(object):
     def get_port(self, context, id, fields=None):
         """Retrieve a port.
 
-        : param context: quantum api request context
-        : param id: UUID representing the port to fetch.
-        : param fields: a list of strings that are valid keys in a
-            port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+        :param context: quantum api request context
+        :param id: UUID representing the port to fetch.
+        :param fields: a list of strings that are valid keys in a port
+                       dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -258,18 +280,20 @@ class QuantumPluginBaseV2(object):
 
         The contents of the list depends on the identity of the user making
         the request (as indicated by the context) as well as any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a port as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
-        : param fields: a list of strings that are valid keys in a
-            port dictionary as listed in the RESOURCE_ATTRIBUTE_MAP
-            object in quantum/api/v2/attributes.py. Only these fields
-            will be returned.
+
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a port as listed in the  :obj:`RESOURCE_ATTRIBUTE_MAP`
+                        object in :file:`quantum/api/v2/attributes.py`. Values
+                        in this dictiontary are an iterable containing values
+                        that will be used for an exact match comparison for
+                        that value.  Each result returned by this function will
+                        have matched one of the values for each key in filters.
+        :param fields: a list of strings that are valid keys in a
+                       port dictionary as listed in the
+                       :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                       :file:`quantum/api/v2/attributes.py`. Only these fields
+                       will be returned.
         """
         pass
 
@@ -278,17 +302,19 @@ class QuantumPluginBaseV2(object):
 
         The result depends on the identity of the user making the request
         (as indicated by the context) as well as any filters.
-        : param context: quantum api request context
-        : param filters: a dictionary with keys that are valid keys for
-            a network as listed in the RESOURCE_ATTRIBUTE_MAP object
-            in quantum/api/v2/attributes.py.  Values in this dictiontary
-            are an iterable containing values that will be used for an exact
-            match comparison for that value.  Each result returned by this
-            function will have matched one of the values for each key in
-            filters.
 
-        NOTE: this method is optional, as it was not part of the originally
-              defined plugin API.
+        :param context: quantum api request context
+        :param filters: a dictionary with keys that are valid keys for
+                        a network as listed in the
+                        :obj:`RESOURCE_ATTRIBUTE_MAP` object in
+                        :file:`quantum/api/v2/attributes.py`.  Values in this
+                        dictiontary are an iterable containing values that will
+                        be used for an exact match comparison for that value.
+                        Each result returned by this function will have matched
+                        one of the values for each key in filters.
+
+        .. note:: this method is optional, as it was not part of the originally
+                  defined plugin API.
         """
         raise exceptions.NotImplementedError()
 
@@ -296,7 +322,7 @@ class QuantumPluginBaseV2(object):
     def delete_port(self, context, id):
         """Delete a port.
 
-        : param context: quantum api request context
-        : param id: UUID representing the port to delete.
+        :param context: quantum api request context
+        :param id: UUID representing the port to delete.
         """
         pass