Add a simple example of custom authentication in the documentation

Refs #1471

diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst
index 7f62da6cf5a40691cefd3ba2e0e02175827d27fc..af43bd29dd7d11178d01c14f031cc29d06a6f313 100644 (file)
--- a/docs/user/authentication.rst
+++ b/docs/user/authentication.rst
@@ -100,12 +100,24 @@ want, you can implement it yourself. Requests makes it easy to add your own
 forms of authentication.
 
 To do so, subclass :class:`requests.auth.AuthBase` and implement the
-``__call__()`` method. When an authentication handler is attached to a request,
+``__call__()`` method::
+
+    >>> import requests
+    >>> class MyAuth(requests.auth.AuthBase):
+    ...     def __call__(self, r):
+    ...         # Implement my authentication
+    ...         return r
+    ...
+    >>> url = 'http://httpbin.org/get'
+    >>> requests.get(url, auth=MyAuth())
+    <Response [200]>
+
+When an authentication handler is attached to a request,
 it is called during request setup. The ``__call__`` method must therefore do
 whatever is required to make the authentication work. Some forms of
 authentication will additionally add hooks to provide further functionality.
 
-Examples can be found under the `Requests organization`_ and in the
+Further examples can be found under the `Requests organization`_ and in the
 ``auth.py`` file.
 
 .. _OAuth: http://oauth.net/