From 4f1ebe8069a9b8e78f05eb4b3a0ccb7069b7c1f3 Mon Sep 17 00:00:00 2001 From: Dean Troyer Date: Thu, 5 Dec 2013 13:23:44 -0600 Subject: Update docs for plugins and release notes * Fill out the existing command and man page * Add a plugins page. * Begin the release notes for 0.3.0 Change-Id: I4527fed28a10a9d79fc8f6c1d925a4bf0d0a7a36 --- doc/source/plugins.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 doc/source/plugins.rst (limited to 'doc/source/plugins.rst') diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst new file mode 100644 index 00000000..5cea16cf --- /dev/null +++ b/doc/source/plugins.rst @@ -0,0 +1,46 @@ +======= +Plugins +======= + +The OpenStackClient plugin system is designed so that the plugin need only be +properly installed for OSC to find and use it. It utilizes the +``setuptools`` entry points mechanism to advertise to OSC the +plugin module and supported commands. + +Implementation +-------------- + +Plugins are discovered by enumerating the entry points +found under ``openstack.cli.extension`` and initializing the specified +client module. + +:: + + [entry_points] + openstack.cli.extension = + oscplugin = oscplugin.client + +The client module must implement the following interface functions: + +* ``API_NAME`` - A string containing the plugin API name; this is + the name of the entry point declaring the plugin client module + (``oscplugin = ...`` in the example above) and the group name for + the plugin commands (``openstack.oscplugin.v1 =`` in the example below) +* ``API_VERSION_OPTION`` (optional) - If set, the name of the API + version attribute; this must be a valid Python identifier and + match the destination set in ``build_option_parser()``. +* ``API_VERSIONS`` - A dict mapping a version string to the client class +* ``build_option_parser(parser)`` - Hook to add global options to the parser +* ``make_client(instance)`` - Hook to create the client object + +OSC enumerates the plugin commands from the entry points in the usual manner +defined for the API version: + +:: + + openstack.oscplugin.v1 = + plugin_list = oscplugin.v1.plugin:ListPlugin + plugin_show = oscplugin.v1.plugin:ShowPlugin + +Note that OSC defines the group name as ``openstack..v`` +so the version should not contain the leading 'v' character. -- cgit v1.2.1