Add basic shell documentation for cratonclient

This adds a directory and some basic templates for creating shell
command documentation for python-cratonclient. This creates the shell
sub-directory to allow for individual pages which document each
sub-command in detail.

In the future, that documentation should be further scoped by the
version of the API that it happens to be relevant to. At the moment that
is not a concern so the flatter structure should work fine.

Change-Id: I07bb776c7713283283c86a2907e1c0ba1c763b79

doc/source/index.rst

@@ -14,6 +14,7 @@ Contents:
 
    readme
    installation
+   shell/index
    usage/index
    v1-api-documentation
    authentication-documentation

doc/source/shell/index.rst

@@ -0,0 +1,204 @@
+=======================
+ Craton CLI User Guide
+=======================
+
+After installing ``python-cratonclient`` and ``craton`` binary should be added
+to our PATH. To use the craton command-line client, we need the following
+information:
+
+- URL to speak to Craton with
+
+- Username to use to authenticate to Craton
+
+- Password to use to authenticate to Craton
+
+- Project ID to use to communicate with Craton
+
+These items need to be provided to the craton command-line client. We can pass
+these as command-line arguments:
+
+.. code::
+
+    $ craton --craton-url <craton-url> \
+             --os-username <username> \
+             --os-password <password> \
+             --os-project-id <project-id>
+
+These parameters may also be provided via environment variables. We can create
+a file, similar to OpenStack's ``openrc`` file that contains:
+
+.. code-block:: bash
+
+    # ~/cratonrc
+    export CRATON_URL="<craton-url>"
+    export OS_USERNAME="<username>"
+    export OS_PASSWORD="<password>"
+    export OS_PROJECT_ID="<project-id>"
+
+And then ``source`` it into our environment:
+
+.. code::
+
+    $ source ~/cratonrc
+    # or
+    $ . ~/cratonrc
+
+And finally we can use ``craton`` without those parameters.
+
+
+Top-Level Options
+=================
+
+Craton's command-line client has several top-level options. These are required
+to be specified prior to any sub-command. All of craton's top-level
+command-line options are documented here:
+
+..
+    OPTION TEMPLATE
+    --------------------------8<---------------------------------------
+    .. option:: --<opt-name>[=<descriptive-parameter-name>]
+
+        <Active description of the purpose.>
+
+        Example usage:
+
+        .. code::
+
+            $ craton --<opt-name>[=<example value>] [positional args]
+    -------------------------->8---------------------------------------
+
+
+.. program:: craton
+
+.. option:: --version
+
+    Show the installed version of python-cratonclient.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --version
+
+.. option:: --format={default,json}
+
+    Specify the format of the output to the terminal. The default value is a
+    pretty-printed table of information. Alternatively, users may request
+    pretty-printed JSON.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --format=json host-list
+        $ craton --format=json region-show 1
+
+.. option:: --craton-url=URL
+
+    Specify the URL where Craton is reachable.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --craton-url=https://craton.cloud.corp host-list
+
+.. option:: --craton-version=VERSION
+
+    Control which version of Craton's API the client should use to
+    communicate. At the moment, Craton only supports ``1`` for v1.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --craton-version=1 region-list
+
+.. option:: --os-project-id=OS_PROJECT_ID
+
+    Provide the Project ID to use when authenticating to Craton.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --os-project-id=b9f10eca66ac4c279c139d01e65f96b4 cell-list
+
+.. option:: --os-username=OS_USERNAME
+
+    Provide the Username to use when authenticating to Craton.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --os-username=demo project-list
+
+.. option:: --os-password=OS_PASWORD
+
+    Provide the Pasword to use when authenticating to Craton.
+
+    Example usage:
+
+    .. code::
+
+        $ craton --os-password=demo devices-list
+
+
+Subcommands
+===========
+
+The craton command-line client has several subcommands. These include (but are
+not limited to):
+
+- ``help``
+
+- ``project-create``
+
+- ``project-delete``
+
+- ``project-list``
+
+- ``project-show``
+
+- ``cloud-create``
+
+- ``cloud-delete``
+
+- ``cloud-list``
+
+- ``cloud-show``
+
+- ``region-create``
+
+- ``region-delete``
+
+- ``region-list``
+
+- ``region-show``
+
+- ``cell-create``
+
+- ``cell-delete``
+
+- ``cell-list``
+
+- ``cell-show``
+
+- ``host-create``
+
+- ``host-delete``
+
+- ``host-list``
+
+- ``host-show``
+
+- ``device-list``.
+
+The command-line options available for each command can be found via
+``craton help <subcommand-name>``, e.g.,
+
+.. code::
+
+    $ craton help cell-create
+    $ craton help host-list