Move docs to doc.

To better facilitate the building and publishing of sphinx
documentation by Jenkins we are moving all openstack projects with
sphinx documentation to a common doc tree structure. Documentation
goes in project/doc and build results go in project/doc/build.

Change-Id: I3ae14ac735d9b4c0b534eac9a9c142f8ccaac1b9

1 files changed, 52 insertions, 0 deletions

diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..cff5cc7
--- /dev/null
+++ b/doc/source/shell.rst
@@ -0,0 +1,52 @@
+The :program:`cinder` shell utility
+=========================================
+
+.. program:: cinder
+.. highlight:: bash
+
+The :program:`cinder` shell utility interacts with OpenStack Nova API
+from the command line. It supports the entirety of the OpenStack Nova API.
+
+First, you'll need an OpenStack Nova account and an API key. You get this
+by using the `cinder-manage` command in OpenStack Nova.
+
+You'll need to provide :program:`cinder` with your OpenStack username and
+API key. You can do this with the :option:`--os_username`, :option:`--os_password`
+and :option:`--os_tenant_id` options, but it's easier to just set them as
+environment variables by setting two environment variables:
+
+.. envvar:: OS_USERNAME
+
+    Your OpenStack Nova username.
+
+.. envvar:: OS_PASSWORD
+
+    Your password.
+
+.. envvar:: OS_TENANT_NAME
+
+    Project for work.
+
+.. envvar:: OS_AUTH_URL
+
+    The OpenStack API server URL.
+
+.. envvar:: OS_COMPUTE_API_VERSION
+
+    The OpenStack API version.
+
+For example, in Bash you'd use::
+
+    export OS_USERNAME=yourname
+    export OS_PASSWORD=yadayadayada
+    export OS_TENANT_NAME=myproject
+    export OS_AUTH_URL=http://...
+    export OS_COMPUTE_API_VERSION=1.1
+    
+From there, all shell commands take the form::
+    
+    cinder <command> [arguments...]
+
+Run :program:`cinder help` to get a full list of all possible commands,
+and run :program:`cinder help <command>` to get detailed help for that
+command.