Lots of docs, trying to tidy up examples...

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/library/authenticators.rst b/docs/library/authenticators.rst
new file mode 100644
index 00000000..ec49c246
--- /dev/null
+++ b/docs/library/authenticators.rst
@@ -0,0 +1,30 @@
+:mod:`authenticators`
+=====================
+
+.. module:: authenticators
+
+The authenticators module provides a standard set of authentication methods that can be plugged in to a :class:`.Resource`, as well as providing a template by which to write custom authentication methods.
+
+The base class
+--------------
+
+All authenticators must subclass the :class:`BaseAuthenticator` class and override it's :func:`authenticate` method.
+
+.. class:: BaseAuthenticator
+
+   .. method:: authenticate(request)
+
+      Authenticate the request and return the authentication context or None.
+
+      The default permission checking on :class:`.Resource` will use the allowed_methods attribute for permissions if the authentication context is not None, and use anon_allowed_methods otherwise.
+
+      The authentication context is passed to the handler calls (eg :meth:`.Resource.get`, :meth:`.Resource.post` etc...) in order to allow them to apply any more fine grained permission checking at the point the response is being generated.
+
+      This function must be overridden to be implemented.
+
+Provided authenticators
+-----------------------
+
+.. note::
+
+    TODO - document this module properly