Update CLI usage doc

Added how to set required environment variables and missing
sub-command usage examples.

Change-Id: Ib4ccd707b0bfe3f407923bf9629b91cfcb480065

CONTRIBUTING.rst

@@ -14,4 +14,4 @@ Pull requests submitted through GitHub will be ignored.
 
 Bugs should be filed on Launchpad, not GitHub:
 
-   https://bugs.launchpad.net/https://launchpad.net/python-rsdclient
+   https://launchpad.net/python-rsdclient

README.rst

@@ -1,19 +1,76 @@
-===============================
+================
 python-rsdclient
-===============================
+================
 
 OpenStack client plugin for Rack Scale Design
 
-Please fill here a long description which must be at least 3 lines wrapped on
-80 cols, so that distribution package maintainers can use it in their packages.
-Note that this is a hard requirement.
+This is a client for the `RSD
+<https://www.intel.com/content/www/us/en/architecture-and-technology/rack-scale-design-overview.html>`_
+Pod Manager API, which is based on OpenStack client framework. It provides a
+Python API (``rsdclient/v1`` module) and a RSD specific plugin for
+OpenStack client (``rsdclient/osc``).
+
+Development takes place via the usual OpenStack processes as outlined in the
+`developer guide <https://docs.openstack.org/infra/manual/developers.html>`_. The master
+repository is on `git.openstack.org
+<https://git.openstack.org/cgit/openstack/python-rsdclient>`_.
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/python-rsdclient
 * Source: http://git.openstack.org/cgit/openstack/python-rsdclient
 * Bugs: https://launchpad.net/python-rsdclient
 
-Features
---------
 
-* TODO
+.. contents:: Contents:
+   :local:
+
+Installation
+------------
+
+To use ``openstack rsd`` CLI, the python-openstackclient and python-rsdclient
+should be installed::
+
+    # pip install python-openstackclient
+    # pip install python-rsdclient
+
+To use the CLI, it requires two parts of configuration, OpenStack and RSD login
+info.
+
+At first, you have to provide your OpenStack username, password,
+project, and auth endpoint. You can use configuration options
+``--os-username``, ``--os-password``, ``--os-project-id``
+(or ``--os-project-name``), and ``--os-auth-url``,
+or set the corresponding environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_PROJECT_NAME=project                         # or OS_PROJECT_ID
+    $ export OS_PROJECT_DOMAIN_ID=default
+    $ export OS_USER_DOMAIN_ID=default
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://auth.example.com:5000/identity
+
+Then, you have to provide your RSD username, password,
+SSL certificate with admin privilege, and pod manager URL. You can use
+configuration options ``--rsd-username``, ``--rsd-password``, ``--rsd-verify``,
+and ``--rsd-url``, or set the corresponding environment variables::
+
+    $ export RSD_USERNAME=admin
+    $ export RSD_PASSWORD=password
+    $ export RSD_VERIFY=False     # or RSD_VERIFY=<path to SSL certificate>
+    $ export RSD_URL=https://localhost:8443/
+
+OpenStackClient RSD Plugin
+--------------------------
+
+To get a list of available (sub)commands and options, run::
+
+    $ openstack help rsd
+
+To get usage and options of a command, run::
+
+    $ openstack help rsd <sub-command>
+
+An example of composing a node only with name::
+
+    $ openstack rsd node compose --name "testing node"

doc/source/cli/osc_plugin_cli.rst

@@ -19,11 +19,40 @@ Description
 The OpenStack Client plugin interacts with Rack Scale Design
 through the ``openstack rsd`` command line interface (CLI).
 
-To use ``openstack rsd`` CLI, the python-openstackclient and python-rsdclient should be installed::
+To use ``openstack rsd`` CLI, the python-openstackclient and python-rsdclient
+should be installed::
 
     # pip install python-openstackclient
     # pip install python-rsdclient
 
+To use the CLI, two parts of configuration are required, OpenStack and RSD
+login info.
+
+At first, you have to provide your OpenStack username, password,
+project, and auth endpoint. You can use configuration options
+``--os-username``, ``--os-password``, ``--os-project-id``
+(or ``--os-project-name``), and ``--os-auth-url``,
+or set the corresponding environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_PROJECT_NAME=project                         # or OS_PROJECT_ID
+    $ export OS_PROJECT_DOMAIN_ID=default
+    $ export OS_USER_DOMAIN_ID=default
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://auth.example.com:5000/identity
+
+Then, you have to provide your RSD username, password,
+SSL certificate with admin privilege, and pod manager URL. You can use
+configuration options ``--rsd-username``, ``--rsd-password``, ``--rsd-verify``,
+and ``--rsd-url``, or set the corresponding environment variables::
+
+    $ export RSD_USERNAME=admin
+    $ export RSD_PASSWORD=password
+    $ export RSD_VERIFY=False     # or RSD_VERIFY=<path to SSL certificate>
+    $ export RSD_URL=https://localhost:8443/
+
+
 Getting help
 ============
 
@@ -42,22 +71,34 @@ Examples
 Compose node command allows the user to issue node composition command through
 OpenStackClient(OSC)::
 
-    $ openstack rsd compose
-    --rsd-url "https://localhost:8442/redfish/v1/"
-    --rsd-username "admin"
-    --rsd-password "admin"
-    --rsd-disable-verify
-    --name "Fake-Name"
+    $ openstack rsd node compose [--name <name>]
+                                 [--description <description>]
+                                 [--processor <processor requirements>]
+                                 [--memory <memory requirements>]
+                                 [--remote-drives <remote drives requirements>]
+                                 [--local-drives <local drives requirements>]
+                                 [--ethernet <ethernet requirements>]
+
+Attach specific resource to existing composed node::
+
+    $ openstack rsd node attach [--resource <resource uri>]
+                                [--capacity <size>]
+                                <node>
+
+Detach specific resource from existing composed node::
+
+    $ openstack rsd node detach [--resource <resource uri>]
+                                <node>
 
 Delete composed node allows the user to delete composed node(s) by
 specifying <node_uuid>::
 
-    $ openstack rsd node delete <node_uuid>
+    $ openstack rsd node delete <node> [<node> ...]
 
 Show composed node detail command allows the user to get composed node details
 by specifying <node_uuid>::
 
-    $ openstack rsd node show <node_uuid>
+    $ openstack rsd node show <node>
 
 List composed node command allows the user to list all composed node
 with brief info::
@@ -82,7 +123,16 @@ brief info like below shows::
 Show storage detail command allows the user to display
 the storage service details::
 
-    $ openstack rsd storage show
+    $ openstack rsd storage show <storage service>
+
+List fabric command allows the user to list all fabrics with brief info::
+
+    $ openstack rsd fabric list
+
+Show fabric detail command allows the user to display the fabric details::
+
+    $ openstack rsd fabric show <fabric>
+
 
 Command Reference
 =================

rsdclient/osc/plugin.py

@@ -56,7 +56,7 @@ def build_option_parser(parser):
         metavar='<rsd-api-version>',
         default=utils.env(
             'RSD_API_VERSION',
-            default='1.3'),
+            default=DEFAULT_API_VERSION),
         help='RSD API version, default=' +
              DEFAULT_API_VERSION +
              ' (Env: RSD_API_VERSION)')