updating base keystoneclient documentation

* updated changelog
* described CLI authentication for admin and user
* tweaked API usage docs a bit with formatting and typos

Change-Id: I61c3aab99bb0ecbad1de6d32a767558ca1a2ab5b

4 files changed, 69 insertions, 118 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index bece0aa..bfa63b8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -18,7 +18,7 @@ Contents:
 Contributing
 ============
 
-Code is hosted `on GitHub`_. Submit bugs to the Keystone project on 
+Code is hosted `on GitHub`_. Submit bugs to the Keystone project on
 `Launchpad`_. Submit code to the openstack/python-keystoneclient project using
 `Gerrit`_.
 
diff --git a/doc/source/releases.rst b/doc/source/releases.rst
index 4a9d281..2f1ed42 100644
--- a/doc/source/releases.rst
+++ b/doc/source/releases.rst
@@ -2,105 +2,32 @@
 Release notes
 =============
 
-2.7.0 (October 21, 2011)
-========================
-* Forked from http://github.com/rackspace/python-novaclient
-* Rebranded to python-keystoneclient
-* Refactored to support Keystone API (auth, tokens, services, roles, tenants,
-  users, etc.)
-
-2.5.8 (July 11, 2011)
-=====================
-* returns all public/private ips, not just first one
-* better 'nova list' search options
-
-2.5.7 - 2.5.6 = minor tweaks
-
-2.5.5 (June 21, 2011)
-=====================
-* zone-boot min/max instance count added thanks to comstud
-* create for user added thanks to cerberus
-* fixed tests
-
-2.5.3 (June 15, 2011)
-=====================
-* ProjectID can be None for backwards compatability.
-* README/docs updated for projectId thanks to usrleon
-
-2.5.1 (June 10, 2011)
-=====================
-* ProjectID now part of authentication
+0.1.3 (August 31, 2012)
+=======================
+* changed logging to report request and response independently in --debug mode
+* changed options to use hyphens instead of underscores
+* added support for PKI signed tokens with Keystone
 
-2.5.0 (June 3, 2011)
-====================
-
-* better logging thanks to GridDynamics
-
-2.4.4 (June 1, 2011)
-====================
-
-* added support for GET /servers with reservation_id (and /servers/detail)
 
-2.4.3 (May 27, 2011)
+0.1.2 (July 9, 2012)
 ====================
+* added support for two-way SSL and --insecure option to allow for self-signed
+  certificates
+* added support for password prompting if not provided
+* added support for bash completion for keystone
+* updated CLI options to use dashes instead of underscores
 
-* added support for POST /zones/select (client only, not cmdline)
-
-2.4 (March 7, 2011)
-===================
-
-* added Jacob Kaplan-Moss copyright notices to older/untouched files.
-
-
-2.3 (March 2, 2011)
-===================
-
-* package renamed to python-novaclient. Module to novaclient
-
-
-2.2 (March 1, 2011)
-===================
-
-* removed some license/copywrite notices from source that wasn't
-  significantly changed.
-
-
-2.1 (Feb 28, 2011)
-==================
-
-* shell renamed to nova from novatools
-
-* license changed from BSD to Apache
-
-2.0 (Feb 7, 2011)
-=================
-
-* Forked from https://github.com/jacobian/python-cloudservers
-
-* Rebranded to python-novatools
-
-* Auth URL support
-
-* New OpenStack specific commands added (pause, suspend, etc)
-
-1.2 (August 15, 2010)
+0.1.1 (June 25, 2012)
 =====================
+* corrected versioning
 
-* Support for Python 2.4 - 2.7.
-
-* Improved output of :program:`cloudservers ipgroup-list`.
-
-* Made ``cloudservers boot --ipgroup <name>`` work (as well as ``--ipgroup
-  <id>``).
-
-1.1 (May 6, 2010)
-=================
-
-* Added a ``--files`` option to :program:`cloudservers boot` supporting
-  the upload of (up to five) files at boot time.
-
-* Added a ``--key`` option to :program:`cloudservers boot` to key the server
-  with an SSH public key at boot time. This is just a shortcut for ``--files``,
-  but it's a useful shortcut.
-
-* Changed the default server image to Ubuntu 10.04 LTS.
+0.1.0 (March 29, 2012)
+======================
+* released with OpenStack Essex and Diablo compatibility
+* forked from http://github.com/rackspace/python-novaclient
+* refactored to support Keystone API (auth, tokens, services, roles, tenants,
+  users, etc.)
+* removed legacy arguments of --username, --password, etc in migration to
+  support a cross-openstack unified CLI convention defined at
+  http://wiki.openstack.org/UnifiedCLI
+* required service ID for listing endpoints
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
index cc0daa6..e4baf4b 100644
--- a/doc/source/shell.rst
+++ b/doc/source/shell.rst
@@ -1,5 +1,5 @@
 The :program:`keystone` shell utility
-=========================================
+=====================================
 
 .. program:: keystone
 .. highlight:: bash
@@ -8,15 +8,36 @@ The :program:`keystone` shell utility
 The :program:`keystone` shell utility interacts with OpenStack Keystone API
 from the command line. It supports the entirety of the OpenStack Keystone API.
 
-First, you'll need an OpenStack Keystone account. You get this by using the 
-`keystone-manage` command in OpenStack Keystone.
+To communicate with the API, you will need to be authenticated - and the
+:program:`keystone` provides multiple options for this.
 
-You'll need to provide :program:`keystone` with your OpenStack username and
-password. You can do this with the :option:`--os-username`, :option:`--os-password`.
-You can optionally specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`,
-to scope your token to a specific tenant.  If you don't specify a tenant, you
-will be scoped to your default tenant if you have one.  Instead of using 
-options, it is easier to just set them as environment variables:
+While bootstrapping keystone the authentication is accomplished with a
+shared secret token and the location of the keystone API endpoint. The
+shared secret token is configured in keystone.conf as "admin_token".
+
+You can specify those values on the command line with :option:`--os-token`
+and :option:`--os-endpoint`, or set them in environment variables:
+
+.. envvar:: OS_SERVICE_TOKEN
+
+    Your keystone administrative token
+
+.. envvar:: OS_SERVICE_ENDPOINT
+
+    Your keystone API endpoint
+
+The command line options will override any environment variables set.
+
+If you already have accounts, you can use your OpenStack username and
+password. You can do this with the :option:`--os-username`,
+:option:`--os-password`.
+
+Keystone allows a user to be associated with one or more tenants. To specify
+the tenant for which you want to authorize against, you may optionally
+specify a :option:`--os-tenant-id` or :option:`--os-tenant-name`.
+
+Instead of using options, it is easier to just set them as environment
+variables:
 
 .. envvar:: OS_USERNAME
 
diff --git a/doc/source/using-api.rst b/doc/source/using-api.rst
index d8fa0bc..809093e 100644
--- a/doc/source/using-api.rst
+++ b/doc/source/using-api.rst
@@ -13,11 +13,12 @@ The main concepts in the Keystone API are:
  * endpoints
 
 The Keystone API lets you query and make changes through managers. For example,
-to maipulate tenants, you interact with a
+to manipulate tenants, you interact with a
 ``keystoneclient.v2_0.tenants.TenantManger`` object.
 
-You obtain access to managers through via atributes of the ``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants`` attribute of the ``Client``
-class is a tenant manager::
+You obtain access to managers through via atributes of the
+``keystoneclient.v2_0.client.Client`` object. For example, the ``tenants``
+attribute of the ``Client`` class is a tenant manager::
 
     >>> from keystoneclient.v2_0 import client
     >>> keystone = client.Client(...)
@@ -36,8 +37,8 @@ There are two ways to authenticate against Keystone:
 
 If you are an administrator, you can authenticate by connecting to the admin
 endpoint and using the admin token (sometimes referred to as the service
-token). The token is specified as the ``admin_token`` configuration option in your
-keystone.conf config file, which is typically in /etc/keystone::
+token). The token is specified as the ``admin_token`` configuration option in
+your keystone.conf config file, which is typically in /etc/keystone::
 
     >>> from keystoneclient.v2_0 import client
     >>> token = '012345SECRET99TOKEN012345'
@@ -54,7 +55,7 @@ user::
     >>> tenant_name='openstackDemo'
     >>> auth_url='http://192.168.206.130:5000/v2.0'
     >>> keystone = client.Client(username=username, password=password,
-    ...                         tenant_name, auth_url=auth_url)
+    ...                          tenant_name=tenant_name, auth_url=auth_url)
 
 Creating tenants
 ================
@@ -77,8 +78,9 @@ in the opoenstackDemo tenant. We first need to retrieve the tenant::
     >>> keystone = client.Client(...)
     >>> tenants = keystone.tenants.list()
     >>> my_tenant = [x for x in tenants if x.name=='openstackDemo'][0]
-    >>> my_user = keystone.users.create(name="adminUser", password="secretword",
-    ...                                                   tenant_id=my_tenant.id)
+    >>> my_user = keystone.users.create(name="adminUser",
+    ...                                 password="secretword",
+    ...                                 tenant_id=my_tenant.id)
 
 Creating roles and adding users
 ===============================
@@ -103,7 +105,8 @@ Compute service::
     >>> keystone = client.Client(...)
     >>> service = keystone.services.create(name="nova", service_type="compute",
     ...                                    description="Nova Compute Service")
-    >>> keystone.endpoints.create(region="RegionOne", service_id=service.id,
-    ...            publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
-    ...            adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
-    ...            internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")
+    >>> keystone.endpoints.create(
+    ...     region="RegionOne", service_id=service.id,
+    ...     publicurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
+    ...     adminurl="http://192.168.206.130:8774/v2/%(tenant_id)s",
+    ...     internalurl="http://192.168.206.130:8774/v2/%(tenant_id)s")