Update developer docs for keystoneauth session

The developer docs should tell developers to use keystoneauth1
sessions rather than keystoneclient sessions or passing
arguments to the Client constructors. keystoneclient sessions and
constructing Clients using non-sessions is deprecated.

Change-Id: Ica19b8d6fb2f5d1a9d0d22d4fe08abb266fd6a86

3 files changed, 26 insertions, 17 deletions

diff --git a/doc/source/using-api-v2.rst b/doc/source/using-api-v2.rst
index 6285d21..1b7c5de 100644
--- a/doc/source/using-api-v2.rst
+++ b/doc/source/using-api-v2.rst
@@ -26,8 +26,8 @@ attribute of the ``Client`` class is a tenant manager::
     >>> keystone.tenants.list() # List tenants
 
 You create a valid ``keystoneclient.v2_0.client.Client`` object by passing
-authentication data to the constructor. Authentication and examples of common
-tasks are provided below.
+a :class:`~keystoneauth1.session.Session` to the constructor. Authentication
+and examples of common tasks are provided below.
 
 You can generally expect that when the client needs to propagate an exception
 it will raise an instance of subclass of
@@ -45,22 +45,30 @@ 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::
 
+    >>> from keystoneauth1.identity import v2
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v2_0 import client
     >>> token = '012345SECRET99TOKEN012345'
     >>> endpoint = 'http://192.168.206.130:35357/v2.0'
-    >>> keystone = client.Client(token=token, endpoint=endpoint)
+    >>> auth = v2.Token(auth_url=endpoint, token=token)
+    >>> sess = session.Session(auth=auth)
+    >>> keystone = client.Client(session=sess)
 
 If you have a username and password, authentication is done against the
 public endpoint. You must also specify a tenant that is associated with the
 user::
 
+    >>> from keystoneauth1.identity import v2
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v2_0 import client
     >>> username='adminUser'
     >>> password='secretword'
     >>> tenant_name='openstackDemo'
     >>> auth_url='http://192.168.206.130:5000/v2.0'
-    >>> keystone = client.Client(username=username, password=password,
-    ...                          tenant_name=tenant_name, auth_url=auth_url)
+    >>> auth = v2.Password(username=username, password=password,
+    ...                    tenant_name=tenant_name, auth_url=auth_url)
+    >>> sess = session.Session(auth=auth)
+    >>> keystone = client.Client(session=sess)
 
 Creating tenants
 ================
diff --git a/doc/source/using-api-v3.rst b/doc/source/using-api-v3.rst
index 61b2b9d..5885f7c 100644
--- a/doc/source/using-api-v3.rst
+++ b/doc/source/using-api-v3.rst
@@ -85,11 +85,11 @@ Authenticating Using Sessions
 =============================
 
 Instantiate a :py:class:`keystoneclient.v3.client.Client` using a
-:py:class:`~keystoneclient.session.Session` to provide the authentication
+:py:class:`~keystoneauth1.session.Session` to provide the authentication
 plugin, SSL/TLS certificates, and other data::
 
-    >>> from keystoneclient.auth.identity import v3
-    >>> from keystoneclient import session
+    >>> from keystoneauth1.identity import v3
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v3 import client
     >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
     ...                    user_id='myuserid',
@@ -118,7 +118,7 @@ password::
     ...                          username=username, password=password,
     ...                          user_domain_name=user_domain_name)
 
-A :py:class:`~keystoneclient.session.Session` should be passed to the Client
+A :py:class:`~keystoneauth1.session.Session` should be passed to the Client
 instead. Using a Session you're not limited to authentication using a username
 and password but can take advantage of other more secure authentication
 methods.
diff --git a/doc/source/using-sessions.rst b/doc/source/using-sessions.rst
index cd8fbb4..a5a5a58 100644
--- a/doc/source/using-sessions.rst
+++ b/doc/source/using-sessions.rst
@@ -5,7 +5,7 @@ Using Sessions
 Introduction
 ============
 
-The :py:class:`keystoneclient.session.Session` class was introduced into
+The :py:class:`keystoneauth1.session.Session` class was introduced into
 keystoneclient as an attempt to bring a unified interface to the various
 OpenStack clients that share common authentication and request parameters
 between a variety of services.
@@ -55,8 +55,8 @@ service and fetch a new one.
 
 An example from keystoneclient::
 
-    >>> from keystoneclient.auth.identity import v3
-    >>> from keystoneclient import session
+    >>> from keystoneauth1.identity import v3
+    >>> from keystoneauth1 import session
     >>> from keystoneclient.v3 import client
 
     >>> auth = v3.Password(auth_url='https://my.keystone.com:5000/v3',
@@ -189,11 +189,12 @@ While authentication plugins will endeavour to maintain a consistent set of
 arguments for an ``endpoint_filter`` the concept of an authentication plugin is
 purposefully generic and a specific mechanism may not know how to interpret
 certain arguments and ignore them. For example the
-:py:class:`keystoneclient.auth.token_endpoint.Token` plugin (which is used when
-you want to always use a specific endpoint and token combination) will always
-return the same endpoint regardless of the parameters to ``endpoint_filter`` or
-a custom OpenStack authentication mechanism may not have the concept of
-multiple ``interface`` options and choose to ignore that parameter.
+:py:class:`keystoneauth1.identity.generic.token.Token` plugin (which is used
+when you want to always use a specific endpoint and token combination) will
+always return the same endpoint regardless of the parameters to
+``endpoint_filter`` or a custom OpenStack authentication mechanism may not have
+the concept of multiple ``interface`` options and choose to ignore that
+parameter.
 
 There is some expectation on the user that they understand the limitations of
 the authentication system they are using.