Add documentation for Twiio Capability.

kyleconroy · kyleconroy · commit b7a3b435ea3f · 2011-07-21T17:01:10.000-07:00
diff --git a/docs/api/util.rst b/docs/api/util.rst
@@ -0,0 +1,13 @@
+====================
+:mod:`twilio.util`
+====================
+
+.. automodule:: twilio.util
+
+.. autoclass:: twilio.util.RequestValidator
+   :members:
+
+.. autoclass:: twilio.util.TwilioCapability
+   :members: allow_client_incoming, allow_client_outgoing, generate
+
+
diff --git a/docs/usage/token-generation.rst b/docs/usage/token-generation.rst
@@ -0,0 +1,56 @@
+.. module:: twilio.util
+
+===========================
+Generate Capability Tokens
+===========================
+
+`Twilio Client <http://www.twilio.com/api/client>`_ allows you to make and recieve connections in the browser. You can place a call to a phone on the PSTN network, all without leaving your browser. See the `Twilio Client Quickstart <http:/www.twilio.com/docs/quickstart/client>`_ to get up and running with Twilio Client.
+
+Capability tokens are used by `Twilio Client <http://www.twilio.com/api/client>`_ to provide connection security and authorization. The `Capability Token documentation <http://www.twilio.con/docs/tokens>`_ explains indepth the purpose and features of these tokens.
+
+:class:`TwilioCapability` is responsible for the creation of these capability tokens. You'll need your Twilio AccountSid and AuthToken.
+
+.. code-block:: python
+
+    from twilio.util import TwilioCapability
+
+    account_sid = "AC123123"
+    auth_token = "secret"
+
+    capability = TwilioCability(account_sid, auth_token)
+
+
+Allow Incoming Connections
+==============================
+
+Before a device running `Twilio Client <http://www.twilio.com/api/client>`_ can recieve incoming connections, the instance must first register a name (such as "Alice" or "Bob"). The :meth:`allow_client_incoming` method adds the client name to the capability token.
+
+.. code-block:: python
+
+    capability.allow_client_incoming("Alice")
+
+
+Allow Outgoing Connections
+==============================
+
+To make an outgoing connection from a `Twilio Client <http://www.twilio.com/api/client>`_ device, you'll need to choose a `Twilio Application <http://www.twilio.com/docs/api/rest/applications>`_ to handle TwiML URLs. A Twilio Application is a collection of URLs responsible for outputing valid TwiML to control phone calls and SMS.
+
+.. code-block:: python
+
+    application_sid = "AP123123" # Twilio Application Sid
+    capability.allow_client_outgoing(application_sid)
+
+Generate a Token
+==================
+
+.. code-block:: python
+
+    token = capability.generate()
+
+By default, this token will expire in one hour. If you'd like to change the token expiration, :meth:`generate` takes an optional :attr:`expires` argument.
+
+.. code-block:: python
+
+    token = capability.generate(expires=600)
+
+This token will now expire in 10 minutes. If you haven't guessed already, :attr:`expires` is expressed in seconds.
