Updated Sphinx documentation

- Added examples using the API
- Added API reference pages
- Added docstrings to classes so they would be picked up by sphinx
- Removed warning about CLI coming soon

Change-Id: I6e187efe508c5ae310ec97efe4650495f958306d

docs/api.rst

@@ -1,25 +0,0 @@
-The :mod:`keystoneclient` Python API
-====================================
-
-.. module:: keystoneclient
-   :synopsis: A client for the OpenStack Keystone API.
-
-.. currentmodule:: keystoneclient.generic.client
-
-.. autoclass:: Client
-
-    .. automethod:: discover
-
-.. currentmodule:: keystoneclient.v2_0.client
-
-.. autoclass:: Client
-
-    .. automethod:: authenticate
-
-
-For more information, see the reference documentation:
-
-.. toctree::
-   :maxdepth: 2
-
-   ref/index

docs/index.rst

@@ -2,18 +2,15 @@ Python bindings to the OpenStack Keystone API
 ==================================================
 
 This is a client for OpenStack Keystone API. There's :doc:`a Python API
-<api>` (the :mod:`keystoneclient` module), and a :doc:`command-line script
+<using-api>` (the :mod:`keystoneclient` module), and a :doc:`command-line script
 <shell>` (installed as :program:`keystone`).
 
-You'll need an `OpenStack Keystone` account, which you can get by
-using `keystone-manage`.
-
 Contents:
 
 .. toctree::
    :maxdepth: 1
 
-   api
+   using-api
    shell
    ref/index
    releases
@@ -21,9 +18,13 @@ Contents:
 Contributing
 ============
 
-Development takes place `on GitHub`__; please file bugs/pull requests there.
+Code is hosted `on GitHub`_. Submit bugs to the Keystone project on 
+`Launchpad`_. Submit code to the openstack/python-keystoneclient project using
+`Gerrit`_.
 
-__ https://github.com/4P/python-keystoneclient
+.. _on GitHub: https://github.com/openstack/python-keystoneclient
+.. _Launchpad: https://launchpad.net/keystone
+.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
 
 Run tests with ``python setup.py test``.
 

docs/ref/client.rst

@@ -0,0 +1,8 @@
+Client
+======
+
+.. currentmodule:: keystoneclient.v2_0.client
+
+.. autoclass:: Client
+
+    .. automethod:: authenticate

docs/ref/endpoints.rst

@@ -0,0 +1,11 @@
+==============================
+Endpoint Manager and Endpoints
+==============================
+
+
+
+.. currentmodule:: keystoneclient.v2_0.endpoints
+
+.. automodule:: keystoneclient.v2_0.endpoints
+    :members:
+

docs/ref/generic-client.rst

@@ -0,0 +1,12 @@
+Generic client
+==============
+
+Use the generic client to obtain access to a specific endpoint version.
+
+
+.. currentmodule:: keystoneclient.generic.client
+
+.. autoclass:: Client
+
+    .. automethod:: discover
+

docs/ref/index.rst

@@ -6,4 +6,11 @@ The following API reference documents are available:
 .. toctree::
    :maxdepth: 1
 
+   client
+   generic-client
+   tenants
+   users
+   roles
+   services
+   endpoints
    exceptions

docs/ref/roles.rst

@@ -0,0 +1,9 @@
+======================
+Role Manager and Roles
+======================
+
+.. currentmodule:: keystoneclient.v2_0.roles
+
+.. automodule:: keystoneclient.v2_0.roles
+    :members:
+

docs/ref/services.rst

@@ -0,0 +1,11 @@
+============================
+Service Manager and Services
+============================
+
+
+
+.. currentmodule:: keystoneclient.v2_0.services
+
+.. automodule:: keystoneclient.v2_0.services
+    :members:
+

docs/ref/tenants.rst

@@ -0,0 +1,11 @@
+==========================
+Tenant Manager and Tenants
+==========================
+
+
+
+.. currentmodule:: keystoneclient.v2_0.tenants
+
+.. automodule:: keystoneclient.v2_0.tenants
+    :members:
+

docs/ref/users.rst

@@ -0,0 +1,9 @@
+======================
+User Manager and Users
+======================
+
+.. currentmodule:: keystoneclient.v2_0.users
+
+.. automodule:: keystoneclient.v2_0.users
+    :members:
+

docs/shell.rst

@@ -4,10 +4,6 @@ The :program:`keystone` shell utility
 .. program:: keystone
 .. highlight:: bash
 
-.. warning:: COMING SOON
-
-    The command line interface is not yet completed. This document serves
-    as a reference for the implementation.
 
 The :program:`keystone` shell utility interacts with OpenStack Keystone API
 from the command line. It supports the entirety of the OpenStack Keystone API.

docs/using-api.rst

@@ -0,0 +1,109 @@
+==============
+The client API
+==============
+
+Introduction
+============
+The main concepts in the Keystone API are:
+
+ * tenants
+ * users
+ * roles
+ * services
+ * endpoints
+
+The Keystone API lets you query and make changes through managers. For example,
+to maipulate 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::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> 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.
+
+Authenticating
+==============
+
+There are two ways to authenticate against Keystone:
+ * against the admin endpoint with the admin token
+ * against the public endpoint with a username and password
+
+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::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> token = '012345SECRET99TOKEN012345'
+    >>> endpoint = 'http://192.168.206.130:35357/v2.0'
+    >>> keystone = client.Client(token=token, endpoint=endpoint)
+
+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 keystoneclient.v2_0 import client
+    >>> username='adminUser'
+    >>> password='secreetword'
+    >>> 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)
+
+Creating tenants
+================
+
+This example will create a tenant named *openStackDemo*::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> keystone.tenants.create(tenant_name="openstackDemo",
+    ...                         description="Default Tenant", enabled=True)
+    <Tenant {u'id': u'9b7962da6eb04745b477ae920ad55939', u'enabled': True, u'description': u'Default Tenant', u'name': u'openstackDemo'}>
+
+Creating users
+==============
+
+This example will create a user named *adminUser* with a password *secretword*
+in the opoenstackDemo tenant. We first need to retrieve the tenant::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> 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)
+
+Creating roles and adding users
+===============================
+
+This example will create an admin role and add the *my_user* user to that
+role, but only for the *my_tenant* tenant:
+
+    >>> from keystoneclient.v2_0 import client
+    >>> keystone = client.Client(...)
+    >>> role = keystone.roles.create('admin')
+    >>> my_tenant = ...
+    >>> my_user = ...
+    >>> keystone.roles.add_user_role(my_user, role, my_tenant)
+
+Creating services and endpoints
+===============================
+
+This example will create the service and corresponding endpoint for the
+Compute service::
+
+    >>> from keystoneclient.v2_0 import client
+    >>> 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")

keystoneclient/v2_0/endpoints.py

@@ -17,17 +17,22 @@ from keystoneclient import base
 
 
 class Endpoint(base.Resource):
+    """Represents a Keystone endpoint"""
     def __repr__(self):
         return "<Endpoint %s>" % self._info
 
 
 class EndpointManager(base.ManagerWithFind):
+    """Manager class for manipulating Keystone endpoints"""
+
     resource_class = Endpoint
 
     def list(self):
+        """List all available endpoints"""
         return self._list('/endpoints', 'endpoints')
 
     def create(self, region, service_id, publicurl, adminurl, internalurl):
+        """Create a new endpoint"""
         body = {'endpoint': {'region': region,
                   'service_id': service_id,
                   'publicurl': publicurl,
@@ -36,4 +41,5 @@ class EndpointManager(base.ManagerWithFind):
         return self._create('/endpoints', body, 'endpoint')
 
     def delete(self, id):
+        """Delete an endpoint"""
         return self._delete('/endpoints/%s' % id)

keystoneclient/v2_0/roles.py

@@ -18,6 +18,7 @@ from keystoneclient import base
 
 
 class Role(base.Resource):
+    """Represents a Keystone role"""
     def __repr__(self):
         return "<Role %s>" % self._info
 
@@ -26,6 +27,7 @@ class Role(base.Resource):
 
 
 class RoleManager(base.ManagerWithFind):
+    """Manager class for manipulating Keystone roles"""
     resource_class = Role
 
     def get(self, role):

keystoneclient/v2_0/services.py

@@ -18,24 +18,30 @@ from keystoneclient import base
 
 
 class Service(base.Resource):
+    """Represents a Keystone service"""
     def __repr__(self):
         return "<Service %s>" % self._info
 
 
 class ServiceManager(base.ManagerWithFind):
+    """Manager class for manipulating Keystone services"""
     resource_class = Service
 
     def list(self):
+        """List available services"""
         return self._list("/OS-KSADM/services", "OS-KSADM:services")
 
     def get(self, id):
+        """Retrieve a service by id"""
         return self._get("/OS-KSADM/services/%s" % id, "OS-KSADM:service")
 
     def create(self, name, service_type, description):
+        """Create a new service"""
         body = {"OS-KSADM:service": {'name': name,
                                      'type': service_type,
                                      'description': description}}
         return self._create("/OS-KSADM/services", body, "OS-KSADM:service")
 
     def delete(self, id):
+        """Delete a service"""
         return self._delete("/OS-KSADM/services/%s" % id)

keystoneclient/v2_0/tenants.py

@@ -20,6 +20,15 @@ from keystoneclient import base
 
 
 class Tenant(base.Resource):
+    """Represents a Keystone tenant
+
+    Attributes:
+        * id: a uuid that identifies the tenant
+        * name: tenant name
+        * description: tenant description
+        * enabled: boolean to indicate if tenant is enabled
+
+    """
     def __repr__(self):
         return "<Tenant %s>" % self._info
 
@@ -56,6 +65,7 @@ class Tenant(base.Resource):
 
 
 class TenantManager(base.ManagerWithFind):
+    """Manager class for manipulating Keystone tenants"""
     resource_class = Tenant
 
     def get(self, tenant_id):
@@ -64,6 +74,7 @@ class TenantManager(base.ManagerWithFind):
     def create(self, tenant_name, description=None, enabled=True):
         """
         Create a new tenant.
+
         """
         params = {"tenant": {"name": tenant_name,
                              "description": description,
@@ -74,7 +85,13 @@ class TenantManager(base.ManagerWithFind):
     def list(self, limit=None, marker=None):
         """
         Get a list of tenants.
+
+        :param integer limit: maximum number to return. (optional)
+        :param string marker: use when specifying a limit and making
+                              multiple calls for querying. (optional)
+
         :rtype: list of :class:`Tenant`
+
         """
 
         params = {}

keystoneclient/v2_0/users.py

@@ -20,6 +20,7 @@ from keystoneclient import base
 
 
 class User(base.Resource):
+    """Represents a Keystone user"""
     def __repr__(self):
         return "<User %s>" % self._info
 
@@ -31,6 +32,7 @@ class User(base.Resource):
 
 
 class UserManager(base.ManagerWithFind):
+    """Manager class for manipulating Keystone users"""
     resource_class = User
 
     def get(self, user):