From 7b110511d2553e4096950032315e34085e4f311f Mon Sep 17 00:00:00 2001
From: Richard Theis <rtheis@us.ibm.com>
Date: Thu, 10 Dec 2015 13:30:21 -0600
Subject: [PATCH] Doc: Add optional command specs process

The developer documentation has been updated to include an
optional command specs process. This process may be used
to work out the specifications for new commands, objects
and actions before their implementation.

This new process could assist in the implementation of
additional neutron support in OSC.

Change-Id: I62f7472435a9caacee0d1b4c8d35417c123b5a44
---
 doc/source/index.rst                         |  1 +
 doc/source/specs/command-objects/example.rst | 86 ++++++++++++++++++++
 doc/source/specs/commands.rst                | 43 ++++++++++
 3 files changed, 130 insertions(+)
 create mode 100644 doc/source/specs/command-objects/example.rst
 create mode 100644 doc/source/specs/commands.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 49929972c3..bb0f0854a7 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -48,6 +48,7 @@ Developer Documentation
    developing
    command-options
    command-wrappers
+   specs/commands
 
 Project Goals
 -------------
diff --git a/doc/source/specs/command-objects/example.rst b/doc/source/specs/command-objects/example.rst
new file mode 100644
index 0000000000..6f8b058844
--- /dev/null
+++ b/doc/source/specs/command-objects/example.rst
@@ -0,0 +1,86 @@
+=======
+example
+=======
+
+This is a specification for the ``example`` command object. It is not intended
+to be a complete template for new commands since other actions, options
+and/or arguments may be used. You can include general specification information
+before the commands below. This information could include links to related material
+or descriptions of similar commands.
+
+[example API name] [example API version]
+
+example create
+--------------
+
+Create new example
+
+.. program:: example create
+.. code:: bash
+
+    os example create
+        <name>
+
+.. describe:: <name>
+
+    New example name
+
+example delete
+--------------
+
+Delete example(s)
+
+.. program:: example delete
+.. code:: bash
+
+    os example delete
+        <example> [<example> ...]
+
+.. describe:: <example>
+
+    Example to delete (name or ID)
+
+example list
+------------
+
+List examples
+
+.. program:: example list
+.. code:: bash
+
+    os example list
+
+example set
+-----------
+
+Set example properties
+
+.. program:: example set
+.. code:: bash
+
+    os example set
+        [--name <new-name>]
+        <example>
+
+.. option:: --name <new-name>
+
+    New example name
+
+.. describe:: <example>
+
+    Example to modify (name or ID)
+
+example show
+------------
+
+Display example details
+
+.. program:: example show
+.. code:: bash
+
+    os example show
+        <example>
+
+.. describe:: <example>
+
+    Example to display (name or ID)
diff --git a/doc/source/specs/commands.rst b/doc/source/specs/commands.rst
new file mode 100644
index 0000000000..55bf947651
--- /dev/null
+++ b/doc/source/specs/commands.rst
@@ -0,0 +1,43 @@
+=============
+Command Specs
+=============
+
+Specifications for new commands, objects and actions are listed below.
+These specifications have not been implemented. See
+:doc:`Command List <../command-list>` for implemented commands and
+:doc:`Command Structure <../commands>` for implemented objects and actions.
+
+It is optional to propose a specifications patch for new commands,
+objects and actions here before submitting the implementation. Once your
+specifications patch merges then you may proceed with the implementation.
+Your implementation patches should move applicable portions of the
+specifications patch to the official :doc:`Command List <../command-list>`
+and :doc:`Command Structure <../commands>` documentation.
+
+Objects Specs
+-------------
+
+Add specifications for new objects based on the ``example`` object.
+
+* ``example``: (**example API name**) example object description
+
+Actions Specs
+-------------
+
+Add specifications for new actions based on the ``example`` action.
+
+* ``example`` - example action description
+
+Commands Specs
+--------------
+
+Add specifications for new commands based on the commands for the
+``example`` object. The ``example`` commands are not intended to
+be a complete template for new commands since other actions, options
+and/or arguments may be used.
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   command-objects/*