Devref documentation for client command extension support

Change-Id: If71c9e2bbf888b1a68d3b7dc351f7df02f1a380f
Closes-Bug: #1470622

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.

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

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