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

@@ -48,6 +48,7 @@ Developer Documentation
    developing
    command-options
    command-wrappers
+   specs/commands
 
 Project Goals
 -------------

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)

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/*