Updates to the API docs

2 files changed, 40 insertions, 12 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 8b3fabb..62d7800 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -95,6 +95,38 @@ Client
         Returns a reference to the thread local context object.  See
         :py:class:`raven.context.Context` for more information.
 
+    .. py:method:: user_context(data)
+
+        Updates the user context for future events.
+
+        Equivalent to this::
+
+            client.context.merge({'user': data})
+
+    .. py:method:: http_context(data)
+
+        Updates the HTTP context for future events.
+
+        Equivalent to this::
+
+            client.context.merge({'request': data})
+
+    .. py:method:: extra_context(data)
+
+        Update the extra context for future events.
+
+        Equivalent to this::
+
+            client.context.merge({'extra': data})
+
+    .. py:method:: tags_context(data)
+
+        Update the tags context for future events.
+
+        Equivalent to this::
+
+            client.context.merge({'tags': data})
+
 Context
 -------
 
diff --git a/docs/index.rst b/docs/index.rst
index 47d0c43..649cba1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -55,23 +55,19 @@ The most basic use for raven is to record one specific error that occurs::
 Adding Context
 --------------
 
-The raven client internally keeps a thread local mapping that can carry
-additional information.  Whenever a message is submitted to Sentry that
-additional data will be passed along.  This context is available as
-`client.context` and can be modified or cleared.
-
-Example usage:
+Much of the usefulness of Sentry comes from additional context data with
+the events.  The Python client makes this very convenient by providing
+methods to set thread local context data that is then submitted
+automatically with all events.  For instance you can use
+:py:meth:`~raven.Client.user_context` to set the information about the
+current user:
 
 .. sourcecode:: python
 
     def handle_request(request):
-        client.context.merge({'user': {
+        client.user_context({
             'email': request.user.email
-        }})
-        try:
-            ...
-        finally:
-            client.context.clear()
+        })
 
 Deep Dive
 ---------