From 91eeacd89ea9fefbbd98a1a45462debbf275d5f1 Mon Sep 17 00:00:00 2001
From: Richard Theis <rtheis@us.ibm.com>
Date: Mon, 14 Mar 2016 13:12:03 -0500
Subject: [PATCH] Devref: Document OSC interfaces available to plugins

This devref documents the OSC interfaces are officially available
for plugins to implement commands and related unit tests. It also
covers requirements for plugins.

Change-Id: I68caa188e389e400fa9f5fd38f32c76cdd3e0986
---
 doc/source/plugins.rst | 64 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index f5bbd6dd61..2426506a2d 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -45,6 +45,9 @@ python-zaqarclient             using OpenStackClient
 Implementation
 ==============
 
+Client module
+-------------
+
 Plugins are discovered by enumerating the entry points
 found under :py:mod:`openstack.cli.extension` and initializing the specified
 client module.
@@ -60,7 +63,9 @@ The client module must define the following top-level variables:
 * ``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)
+  the plugin commands (``openstack.oscplugin.v1 =`` in the example below).
+  OSC reserves the following API names: ``compute``, ``identity``,
+  ``image``, ``network``, ``object_store`` and ``volume``.
 * ``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()``.
@@ -85,6 +90,9 @@ so the version should not contain the leading 'v' character.
 
 .. code-block:: python
 
+    from openstackclient.common import utils
+
+
     DEFAULT_API_VERSION = '1'
 
     # Required by the OSC plugin interface
@@ -130,6 +138,60 @@ so the version should not contain the leading 'v' character.
                  ' (Env: OS_OSCPLUGIN_API_VERSION)')
         return parser
 
+Client usage of OSC interfaces
+------------------------------
+
+OSC provides the following interfaces that may be used to implement
+the plugin commands:
+
+.. code-block:: python
+
+    # OSC common interfaces available to plugins:
+    from openstackclient.common import command
+    from openstackclient.common import exceptions
+    from openstackclient.common import parseractions
+    from openstackclient.common import logs
+    from openstackclient.common import utils
+
+
+    class DeleteMypluginobject(command.Command):
+        """Delete mypluginobject"""
+
+        ...
+
+        def take_action(self, parsed_args):
+            # Client manager interfaces are availble to plugins.
+            # This includes the OSC clients created.
+            client_manager = self.app.client_manager
+
+            ...
+
+            return
+
+OSC provides the following interfaces that may be used to implement
+unit tests for the plugin commands:
+
+.. code-block:: python
+
+    # OSC unit test interfaces available to plugins:
+    from openstackclient.tests import fakes
+    from openstackclient.tests import utils
+
+    ...
+
+Requirements
+------------
+
+OSC must be included in ``requirements.txt`` or ``test-requirements.txt``
+for the plugin project. Update ``requirements.txt`` if the plugin project
+considers the CLI a required feature. Update ``test-requirements.txt`` if
+the plugin project can be installed as a library with the CLI being an
+optional feature (available when OSC is also installed).
+
+.. code-block:: ini
+
+    python-openstackclient>=X.Y.Z # Apache-2.0
+
 Checklist for adding new OpenStack plugins
 ==========================================