Adding Sahara CLI overview to docs and fixing warnings

New Sahara CLI as OpenStackClient plugin usage overview
added and few warnings during docs generation fixed

Partially implements: blueprint cli-as-openstackclient-plugin

Change-Id: If5b4608429d994c642237d6a73ebd9e1bd985fc5
Closes-bug: #1512690

3 files changed, 65 insertions, 4 deletions

diff --git a/doc/source/how_to_participate.rst b/doc/source/how_to_participate.rst
index 43b6a10..14c1ee0 100644
--- a/doc/source/how_to_participate.rst
+++ b/doc/source/how_to_participate.rst
@@ -59,8 +59,7 @@ How to send your first patch on review?
 
 * Apply and commit your changes
 
-* Make sure that your code passes ``PEP8`` checks and unit-tests.
-  See :doc:`development.guidelines`
+* Make sure that your code passes ``PEP8`` checks and unit-tests
 
 * Send your patch on review
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index ddbaf07..99deb4f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,8 +2,8 @@ Python bindings to the OpenStack Sahara API
 ===========================================
 
 This is a client for OpenStack Sahara API. There's :doc:`a Python API
-<api>` (the :mod:`saharaclient` module), and a :doc:`command-line script
-<shell>` (installed as :program:`sahara`). Each implements the entire
+<api>` (the :mod:`saharaclient` module), and a :doc:`command-line utility
+<shell>` (installed as an OpenStackClient plugin). Each implements the entire
 OpenStack Sahara API.
 
 You'll need credentials for an OpenStack cloud that implements the
@@ -21,6 +21,7 @@ Contents:
    :maxdepth: 2
 
    api
+   shell
    how_to_participate
 
 Contributing
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..23ea500
--- /dev/null
+++ b/doc/source/shell.rst
@@ -0,0 +1,61 @@
+Sahara CLI
+==========
+
+The Sahara shell utility now is part of the OpenStackClient, so all
+shell commands take the following form:
+
+.. code-block:: bash
+
+    $ openstack dataprocessing <command> [arguments...]
+
+To get a list of all possible commands you can run:
+
+.. code-block:: bash
+
+    $ openstack help dataprocessing
+
+To get detailed help for the command you can run:
+
+.. code-block:: bash
+
+    $ openstack help dataprocessing <command>
+
+For more information about abilities and features of OpenStackClient CLI you
+can refer to `OpenStackClient documentation <http://docs.openstack.org/developer/python-openstackclient/>`_
+
+Configuration
+-------------
+
+The CLI is configured via environment variables and command-line options which
+are described in http://docs.openstack.org/developer/python-openstackclient/authentication.html.
+
+Authentication using username/password is most commonly used and can be
+provided with environment variables:
+
+.. code-block:: bash
+
+   export OS_AUTH_URL=<url-to-openstack-identity>
+   export OS_PROJECT_NAME=<project-name>
+   export OS_USERNAME=<username>
+   export OS_PASSWORD=<password>  # (optional)
+
+or command-line options:
+
+.. code-block:: bash
+
+   --os-auth-url <url>
+   --os-project-name <project-name>
+   --os-username <username>
+   [--os-password <password>]
+
+Additionally :program:`sahara` API url can be configured with parameter:
+
+.. code-block:: bash
+
+    --os-data-processing-url
+
+or with environment variable:
+
+.. code-block:: bash
+
+    export OS_DATA_PROCESSING_URL=<url-to-sahara-API>