From 28884ffaa49cb6ff7f0c18a646c55b0387d6282f Mon Sep 17 00:00:00 2001 From: Lorin Hochstein Date: Sun, 26 May 2013 16:42:21 -0400 Subject: [PATCH] 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 --- doc/source/devref/plugin-api.rst | 7 + doc/source/index.rst | 1 + quantum/quantum_plugin_base_v2.py | 264 ++++++++++++++++-------------- 3 files changed, 153 insertions(+), 119 deletions(-) create mode 100644 doc/source/devref/plugin-api.rst diff --git a/doc/source/devref/plugin-api.rst b/doc/source/devref/plugin-api.rst new file mode 100644 index 000000000..fbf72abf7 --- /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 654768d5d..5539a78d4 100644 --- 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 35bbcf997..43d21f1c6 100644 --- 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