Add Usage documentation

Added Usage and Reference documentation.

Change-Id: I37469addf1d44db23ca04302cd5f7ca96c01b5e0

5 files changed, 257 insertions, 6 deletions

diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst
new file mode 100644
index 0000000..a0712a8
--- /dev/null
+++ b/doc/source/authentication.rst
@@ -0,0 +1,68 @@
+Authentication
+==============
+
+Keystone Authentication
+-----------------------
+
+The client defers authentication to `Keystone Sessions`_, which provide several
+authentication plugins in the `keystoneclient.auth` namespace.  Below we give
+examples of the most commonly used auth plugins.
+
+.. _`Keystone Sessions`: http://docs.openstack.org/developer/python-keystoneclient/using-sessions.html
+
+Keystone API Version 3 Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Authentication using Keystone API Version 3 can be achieved using the
+`keystoneclient.auth.identity.v3.Password` auth plugin.
+
+Example::
+
+    from keystoneclient.auth import identity
+    from keystoneclient import session
+    from barbicanclient import client
+
+    auth = identity.v3.Password(auth_url='http://localhost:5000/v3',
+                                username='admin_user',
+                                user_domain_name='Default',
+                                password='password',
+                                project_name='demo'
+                                project_domain_name='Default')
+    sess = session.Session(auth=auth)
+    barbican = client.Client(session=sess)
+
+Keystone API Version 2 Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Authentication using Keystone API Version 2 can be achieved using the
+`keystoneclient.auth.identity.v3.Password` auth plugin.
+
+Example::
+
+    from keystoneclient.auth import identity
+    from keystoneclient import session
+    from barbicanclient import client
+
+    auth = identity.v2.Password(auth_url='http://localhost:5000/v2.0',
+                                username='admin_user',
+                                password='password',
+                                tenant_name='demo')
+    sess = session.Session(auth=auth)
+    barbican = client.Client(session=sess)
+
+Unauthenticated Context
+-----------------------
+
+Sometimes it may be useful to work with the client in an unauthenticated
+context, for example when using a development instance of Barbican that is
+not yet configured to use Keystone for authentication.  In this case, the
+Barbican Service endpoint must be provided, in addition to the Project ID that
+will be used for context (i.e. the project that owns the secrets you'll be
+working with).
+
+Example::
+
+    from barbicanclient import client
+
+    barbican = client.Client(endpoint='http://localhost:9311',
+                             project_id='123456')
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f45fef6..a6ee632 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,17 +3,22 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to python-barbicanclient's documentation!
-========================================================
+Python bindings to the OpenStack Key Management API (Barbican)
+==============================================================
+
+This is a client for OpenStack Key Management API (Barbican).  There's a Python
+API (the `barbicanclient` module), and a command-line interface (installed as
+`barbican`).
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
    installation
+   authentication
    usage
+   reference
    contributing
 
 Indices and tables
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 38ba804..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
\ No newline at end of file
diff --git a/doc/source/reference.rst b/doc/source/reference.rst
new file mode 100644
index 0000000..8ad7214
--- /dev/null
+++ b/doc/source/reference.rst
@@ -0,0 +1,48 @@
+=========
+Reference
+=========
+
+Client
+======
+
+.. autoclass:: barbicanclient.client.Client
+   :members:
+
+Secrets
+=======
+
+.. autoclass:: barbicanclient.secrets.SecretManager
+   :members:
+
+.. autoclass:: barbicanclient.secrets.Secret
+   :members:
+
+Orders
+======
+
+.. autoclass:: barbicanclient.orders.OrderManager
+   :members:
+
+.. autoclass:: barbicanclient.orders.Order
+   :members:
+
+.. autoclass:: barbicanclient.orders.KeyOrder
+   :members:
+
+.. autoclass:: barbicanclient.orders.AsymmetricOrder
+   :members:
+
+Containers
+==========
+
+.. autoclass:: barbicanclient.containers.ContainerManager
+   :members:
+
+.. autoclass:: barbicanclient.containers.Container
+   :members:
+
+.. autoclass:: barbicanclient.containers.RSAContainer
+   :members:
+
+.. autoclass:: barbicanclient.containers.CertificateContainer
+   :members:
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 2d062b2..4ba475e 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,6 +2,137 @@
 Usage
 ========
 
-To use python-barbicanclient in a project::
+To use barbicanclient, you must first create an instance of the
+:class:`barbicanclient.client.Client` class.
+
+The client uses Keystone Sessions for both authentication and for handling HTTP
+requests.  You can provide authentication credentials to the client by creating
+a Keystone Session with the appropriate auth plugin and then passing that
+session to the new Client.
+
+See :doc:`authentication` for more details.
+
+Example::
+
+    from barbicanclient import client
+
+    barbican = client.Client(...)
+
+The client object has different attributes that can be used to interact with
+the Barbican service.  Each attribute represents an entity in the Barbican
+service:  Secrets, Orders and Containers.
+
+Secrets
+=======
+
+Secrets represent keys, credentials, and other sensitive data that is stored
+by the Barbican service.  To store or retrieve a secret in the Barbican
+service you should use the different methods of the :class:`barbicanclient.secrets.SecretManager`
+class that is exposed as the `secrets` attribute of the Client.
+
+Example::
+
+    # Create a random encryption key and store it in Barbican
+
+    import base64
+    import os
+    from barbicanclient import client
+
+    barbican = client.Client(...)
+
+    my_secret = barbican.secrets.create()
+    my_secret.name = 'Encryption Key'
+    my_secret.payload = base64.b64encode(os.urandom(32))
+    my_secret.payload_content_type = 'application/octet-stream'
+    my_secret.payload_content_encoding = 'base64'
+
+    my_secret_ref = my_secret.store()
+
+The secret reference returned by :meth:`barbicanclient.secrets.SecretManager.store`
+can later be used to retrieve the secret data from barbican.
+
+Example::
+
+    # Retrieve Secret from secret reference
+
+    retrieved_secret = barbican.secrets.get(my_secret_ref)
+    key = retrieved_secret.payload
+
+Orders
+======
+
+Orders are used to request secret material to be created by the Barbican
+service.  Submitting an order will result in a Secret being created on your
+behalf.  The Secret can then be used like any Secret you may have uploaded
+yourself.  Orders should be created using the factory methods in the
+:class:`barbicanclient.orders.OrderManager` instance in the `orders`
+attribute of the `Client`.
+
+Example::
+
+    # Submit an order to generate a random encryption key
+
+    from barbicanclient import client
+
+    barbican = client.Client(...)
+
+    my_order = barbican.orders.key_order()
+    my_order.algorithm = 'AES'
+    my_order.mode = 'CBC'
+    my_order.bit_length = 256
+
+    my_order_ref = my_order.submit()
+
+The order reference returned by :meth:`barbicanclient.orders.Order.submit()`
+can later be used to retrieve the order from Barbican.
+
+Example::
+
+    # Retrieve Order from order reference
+
+    retrieved_order = barbican.orders.get(my_order_ref)
+
+Once your order has been processed by Barbican, the order status will be set
+to `'ACTIVE'`.  An active order will contain the reference to the requested
+secret (or container).
+
+Example::
+
+    # Retrieve Encryption Key generated by the above KeyOrder
+
+    generated_secret = barbican.secrets.get(retrieved_order.secret_ref)
+    key = generated_secret.payload
+
+Currently the client can submit :class:`barbicanclient.orders.KeyOrder` orders
+for Keys suitable for symmetric encryption, and :class:`barbicanclient.orders.AsymmetricOrder`
+for Asymmetric keys such as RSA keys.
+
+Containers
+==========
+
+Containers can be either arbitrary groupings of `Secrets` or a strict
+grouping of Secrets, such as the Public and Private keys of an RSA keypair.
+
+Containers should be managed using the :class:`barbicanclient.containers.ContainerManager`
+instance in the `containers` attribute of the `Client`
+
+Example::
+
+    # Add the Secrets created above to a container
+
+    my_container = barbican.containers.create()
+
+    my_container.add('Retrieved Secret', retrieved_secret)
+    my_container.add('Generated Secret', generated_secret)
+
+    my_container_ref = my_container.store()
+
+The container reference returned by :meth:`barbicanclient.containers.Container.store`
+can later be used to retrieve the container from Barbican.
+
+Example::
+
+    # Retrieve container from Barbican
+
+    retrieved_container = barbican.containers.get(my_container_ref)
 
-    import barbicanclient
\ No newline at end of file