From ab7d9e805a86b6178ec8e462ad71391de0ce4417 Mon Sep 17 00:00:00 2001
From: Gal Sagie <gal.sagie@huawei.com>
Date: Tue, 7 Jul 2015 09:42:37 +0300
Subject: [PATCH] Devref documentation for client command extension support

Change-Id: If71c9e2bbf888b1a68d3b7dc351f7df02f1a380f
Closes-Bug: #1470622
---
 .../devref/client_command_extensions.rst      | 40 +++++++++++++++++++
 doc/source/devref/index.rst                   | 29 ++++++++++++++
 doc/source/index.rst                          | 12 +++++-
 3 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/devref/client_command_extensions.rst
 create mode 100644 doc/source/devref/index.rst

diff --git a/doc/source/devref/client_command_extensions.rst b/doc/source/devref/client_command_extensions.rst
new file mode 100644
index 000000000..8be6245b5
--- /dev/null
+++ b/doc/source/devref/client_command_extensions.rst
@@ -0,0 +1,40 @@
+=================================
+Client command extension support
+=================================
+
+The client command extension adds support for extending the neutron client while
+considering ease of creation.
+Extensions strongly conform to preexisting neutron commands (/neutron/v2_0/).
+
+A sample extension can be seen at:
+neutronclient/neutron/v2_0/contrib/_fox_sockets.py
+
+Minimum requirements from an extension
+--------------------------------------
+
+* Will have a class that subclasses NeutronClientExtension to provide the
+  requisite version support, paths, and variable names for the client.
+  Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocket
+
+* Will have at least one class that subclasses from the ClientExtension
+  classes to provide the new functionality to the client
+  Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsList
+
+* ClientExtension subclasses must have a shell_command class variable if the
+  command is to be available to the CLI (shell.py)
+  Example: neutronclient.neutron.v2_0.contrib._fox_sockets.FoxInSocketsList
+
+
+Precedence of command loading
+------------------------------
+
+* hard coded commands are loaded first
+* contributed commands (those in /contrib)
+* external commands (installed in the environment) are loaded last
+
+Commands that have the same name will be overwritten by commands that are
+loaded later. To change the execution of a command for your particular
+extension you only need to override the execute method.
+
+Currently this extension support is limited to top-level resources.
+Parent/child relationships may be added if desired.
\ No newline at end of file
diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
new file mode 100644
index 000000000..c23f0a6e3
--- /dev/null
+++ b/doc/source/devref/index.rst
@@ -0,0 +1,29 @@
+..
+      Copyright 2015 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+Developer Guide
+===============
+
+In the Developer Guide, you will find information on Neutron's Client lower level
+programming APIs.
+
+
+Programming HowTos and Tutorials
+--------------------------------
+.. toctree::
+    :maxdepth: 3
+
+    client_command_extensions
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e032df51..d02a5c8f1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -48,6 +48,16 @@ If neutron server does not require authentication, besides these two arguments o
 
 Once you've configured your authentication parameters, you can run ``neutron -h`` to see a complete listing of available commands.
 
+
+Developer Docs
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   devref/index
+
+
 Release Notes
 =============
 
@@ -72,4 +82,4 @@ Release Notes
 * add --endpoint-type and OS_ENDPOINT_TYPE to shell client
 * made the publicURL the default endpoint instead of adminURL
 * add ability to update security group name (requires 2013.2-Havana or later)
-* add flake8 and pbr support for testing and building
+* add flake8 and pbr support for testing and building
\ No newline at end of file