From 4a76e5e02f35afceda3c1a11adb50f8a2e815be3 Mon Sep 17 00:00:00 2001
From: Terry Howe <terrylhowe@gmail.com>
Date: Wed, 22 Oct 2014 14:46:34 -0600
Subject: [PATCH] base auth plugin docs

Change-Id: I9966cf4bb8c9e23517adeee4c061d23a8e71630a
---
 doc/source/base_auth_plugin.rst |  9 ++++++++
 examples/authenticate.py        | 14 ------------
 openstack/auth/base.py          | 38 ++++++++++++++++++++++++++++-----
 3 files changed, 42 insertions(+), 19 deletions(-)
 create mode 100644 doc/source/base_auth_plugin.rst

diff --git a/doc/source/base_auth_plugin.rst b/doc/source/base_auth_plugin.rst
new file mode 100644
index 00000000..52a5369c
--- /dev/null
+++ b/doc/source/base_auth_plugin.rst
@@ -0,0 +1,9 @@
+BaseAuthPlugin
+==============
+.. automodule:: openstack.auth.base
+
+Connection Object
+-----------------
+
+.. autoclass:: openstack.auth.base.BaseAuthPlugin
+   :members:
diff --git a/examples/authenticate.py b/examples/authenticate.py
index e08bf478..9061d508 100644
--- a/examples/authenticate.py
+++ b/examples/authenticate.py
@@ -29,23 +29,9 @@ import sys
 
 from examples import common
 from examples import transport
-from openstack.auth import base
 from openstack import connection
 
 
-class TestAuthenticator(base.BaseAuthPlugin):
-    def __init__(self, token, endpoint):
-        super(TestAuthenticator, self).__init__()
-        self.token = token
-        self.endpoint = endpoint
-
-    def get_token(self, transport, **kwargs):
-        return self.token
-
-    def get_endpoint(self, transport, service, **kwargs):
-        return self.endpoint
-
-
 def make_authenticate(opts):
     args = {
         'auth_plugin': opts.auth_plugin,
diff --git a/openstack/auth/base.py b/openstack/auth/base.py
index 36949449..7481c48a 100644
--- a/openstack/auth/base.py
+++ b/openstack/auth/base.py
@@ -10,6 +10,28 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+The base class for an authenticator.  A plugin must define the get_token,
+get_endpoint, and get_versions methods.  The simpliest example would be
+something that is just given such as::
+
+    class SimpleAuthenticator(base.BaseAuthPlugin):
+        def __init__(self, token, endpoint, versions):
+            super(SimpleAuthenticator, self).__init__()
+            self.token = token
+            self.endpoint = endpoint
+            self.versions = versions
+
+        def get_token(self, transport, **kwargs):
+            return self.token
+
+        def get_endpoint(self, transport, service, **kwargs):
+            return self.endpoint
+
+        def get_versions(self, transport, service, **kwargs):
+            return self.versions
+"""
+
 import abc
 
 import six
@@ -17,7 +39,6 @@ import six
 
 @six.add_metaclass(abc.ABCMeta)
 class BaseAuthPlugin(object):
-    """The basic structure of an authenticator."""
 
     @abc.abstractmethod
     def get_token(self, transport, **kwargs):
@@ -35,6 +56,7 @@ class BaseAuthPlugin(object):
 
         :param transport: A transport object so the authenticator can make
                           HTTP calls.
+        :type transport: :class:`Transport <openstack.transport.Transport>`
         :return string: A token to use.
         """
 
@@ -46,8 +68,11 @@ class BaseAuthPlugin(object):
         authenticator should use best effort with the information available to
         determine the endpoint.
 
-        :param Transport transport: Authenticator may need to make HTTP calls.
-        :param ServiceFilter service: Filter to identify the desired service.
+        :param transport: Authenticator may need to make HTTP calls.
+        :type transport: :class:`Transport <openstack.transport.Transport>`
+        :param service: Filter to identify the desired service.
+        :type service: :class:`ServiceFilter
+            <openstack.auth.service_filter.ServiceFilter>`
 
         :returns string: The base URL that will be used to talk to the
                          required service or None if not available.
@@ -57,8 +82,11 @@ class BaseAuthPlugin(object):
     def get_versions(self, transport, service, **kwargs):
         """Return the valid versions for the given service.
 
-        :param Transport transport: Authenticator may need to make HTTP calls.
-        :param ServiceFilter service: Filter to identify the desired service.
+        :param transport: Authenticator may need to make HTTP calls.
+        :type transport: :class:`Transport <openstack.transport.Transport>`
+        :param service: Filter to identify the desired service.
+        :type service: :class:`ServiceFilter
+            <openstack.auth.service_filter.ServiceFilter>`
 
         :returns list: Returns list of versions that match the filter.
         """