Mention keystoneclient.Session use in docs

Jamie added some excellent "Using Sessions" docs to keystoneclient in
I5e44c1029ce160cb2798cfb8a535aa9f3311799a. These will be published to

  http://docs.openstack.org/developer/python-keystoneclient/using-sessions.html

once the version after 0.9.0 is released.

Let's add a brief example on how to use this API and reference the
keystoneclient docs.

Change-Id: Icbcef45f13c1f962c90aa3db9dde4360520166ff

doc/source/api.rst

@@ -16,6 +16,23 @@ First create a client instance with your credentials::
 
 Here ``VERSION`` can be: ``1.1``, ``2`` and ``3``.
 
+Alternatively, you can create a client instance using the keystoneclient
+session API::
+
+    >>> from keystoneclient.auth.identity import v2
+    >>> from keystoneclient import session
+    >>> from novaclient.client import Client
+    >>> auth = v2.Password(auth_url=AUTH_URL,
+                           username=USERNAME,
+                           password=PASSWORD,
+                           tenant_name=PROJECT_ID)
+    >>> sess = session.Session(auth=auth)
+    >>> nova = client.Client(VERSION, session=sess)
+
+For more information on this keystoneclient API, see `Using Sessions`_.
+
+.. _Using Sessions: http://docs.openstack.org/developer/python-keystoneclient/using-sessions.html
+
 Then call methods on its managers::
 
     >>> nova.servers.list()

novaclient/v1_1/client.py

@@ -55,6 +55,19 @@ class Client(object):
 
         >>> client = Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL)
 
+    Or, alternatively, you can create a client instance using the
+    keystoneclient.session API::
+
+        >>> from keystoneclient.auth.identity import v2
+        >>> from keystoneclient import session
+        >>> from novaclient.client import Client
+        >>> auth = v2.Password(auth_url=AUTH_URL,
+                               username=USERNAME,
+                               password=PASSWORD,
+                               tenant_name=PROJECT_ID)
+        >>> sess = session.Session(auth=auth)
+        >>> nova = client.Client(VERSION, session=sess)
+
     Then call methods on its managers::
 
         >>> client.servers.list()

novaclient/v3/client.py

@@ -40,6 +40,19 @@ class Client(object):
 
         >>> client = Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL)
 
+    Or, alternatively, you can create a client instance using the
+    keystoneclient.session API::
+
+        >>> from keystoneclient.auth.identity import v2
+        >>> from keystoneclient import session
+        >>> from novaclient.client import Client
+        >>> auth = v2.Password(auth_url=AUTH_URL,
+                               username=USERNAME,
+                               password=PASSWORD,
+                               tenant_name=PROJECT_ID)
+        >>> sess = session.Session(auth=auth)
+        >>> nova = client.Client(VERSION, session=sess)
+
     Then call methods on its managers::
 
         >>> client.servers.list()