Merge Marko's doc improvements.

16 files changed, 97 insertions, 79 deletions

diff --git a/djangorestframework/authentication.py b/djangorestframework/authentication.py
index b0ba41aa..1c5c832f 100644
--- a/djangorestframework/authentication.py
+++ b/djangorestframework/authentication.py
@@ -1,10 +1,10 @@
 """
-The ``authentication`` module provides a set of pluggable authentication classes.
+The :mod:`authentication` module provides a set of pluggable authentication classes.
 
-Authentication behavior is provided by adding the ``AuthMixin`` class to a ``View`` .
+Authentication behavior is provided by mixing the :class:`mixins.AuthMixin` class into a :class:`View` class.
 
 The set of authentication methods which are used is then specified by setting the
-``authentication`` attribute on the ``View`` class, and listing a set of authentication classes.
+:attr:`authentication` attribute on the :class:`View` class, and listing a set of authentication classes.
 """
 
 from django.contrib.auth import authenticate
@@ -26,24 +26,23 @@ class BaseAuthenticaton(object):
 
     def __init__(self, view):
         """
-        Authentication classes are always passed the current view on creation.
+        :param view: :class:`Authentication` classes are always passed the current view on creation.
         """
         self.view = view
 
     def authenticate(self, request):
         """
-        Authenticate the request and return a ``User`` instance or None. (*)
-
-        This function must be overridden to be implemented.
-        
-        (*) The authentication context _will_ typically be a ``User`` object,
-        but it need not be.  It can be any user-like object so long as the
-        permissions classes on the view can handle the object and use
-        it to determine if the request has the required permissions or not. 
-
-        This can be an important distinction if you're implementing some token
-        based authentication mechanism, where the authentication context
-        may be more involved than simply mapping to a ``User``.
+        :param request: Request to be authenticated
+        :rtype: :obj:`User` or None [*]_
+       
+        .. [*] The authentication context *will* typically be a :obj:`User`,
+            but it need not be.  It can be any user-like object so long as the
+            permissions classes on the view can handle the object and use
+            it to determine if the request has the required permissions or not. 
+    
+            This can be an important distinction if you're implementing some token
+            based authentication mechanism, where the authentication context
+            may be more involved than simply mapping to a :obj:`User`.
         """
         return None
 
@@ -54,6 +53,10 @@ class BasicAuthenticaton(BaseAuthenticaton):
     """
 
     def authenticate(self, request):
+        """
+        Returns a :obj:`User` if a correct username and password have been supplied
+        using HTTP Basic authentication.  Otherwise returns `None`.  
+        """
         from django.utils.encoding import smart_unicode, DjangoUnicodeDecodeError
         
         if 'HTTP_AUTHORIZATION' in request.META:
@@ -81,6 +84,9 @@ class UserLoggedInAuthenticaton(BaseAuthenticaton):
     """
 
     def authenticate(self, request):
+        """
+        Returns a :obj:`User` if the request session currently has a logged in user, otherwise `None`.
+        """
         # TODO: Switch this back to request.POST, and let FormParser/MultiPartParser deal with the consequences.
         if getattr(request, 'user', None) and request.user.is_active:
             # If this is a POST request we enforce CSRF validation.
diff --git a/djangorestframework/mixins.py b/djangorestframework/mixins.py
index 278d4d4d..e101b788 100644
--- a/djangorestframework/mixins.py
+++ b/djangorestframework/mixins.py
@@ -408,28 +408,6 @@ class AuthMixin(object):
             permission.check_permission(user)
 
 
-##########
-
-class InstanceMixin(object):
-    """
-    Mixin class that is used to identify a view class as being the canonical identifier
-    for the resources it is mapped too.
-    """
-
-    @classmethod
-    def as_view(cls, **initkwargs):
-        """
-        Store the callable object on the resource class that has been associated with this view.
-        """
-        view = super(InstanceMixin, cls).as_view(**initkwargs)
-        if 'resource' in initkwargs:
-            # We do a little dance when we store the view callable...
-            # we need to store it wrapped in a 1-tuple, so that inspect will treat it
-            # as a function when we later look it up (rather than turning it into a method).
-            # This makes sure our URL reversing works ok.      
-            initkwargs['resource'].view_callable = (view,)
-        return view
-
 ########## Resource Mixin ##########
 
 class ResourceMixin(object):
@@ -449,6 +427,9 @@ class ResourceMixin(object):
 
     @property
     def CONTENT(self):
+        """
+        Returns the cleaned, validated request content.
+        """
         if not hasattr(self, '_content'):
             self._content = self.validate_request(self.DATA, self.FILES)
         return self._content
@@ -474,6 +455,28 @@ class ResourceMixin(object):
 
 
 
+##########
+
+class InstanceMixin(object):
+    """
+    Mixin class that is used to identify a view class as being the canonical identifier
+    for the resources it is mapped too.
+    """
+
+    @classmethod
+    def as_view(cls, **initkwargs):
+        """
+        Store the callable object on the resource class that has been associated with this view.
+        """
+        view = super(InstanceMixin, cls).as_view(**initkwargs)
+        if 'resource' in initkwargs:
+            # We do a little dance when we store the view callable...
+            # we need to store it wrapped in a 1-tuple, so that inspect will treat it
+            # as a function when we later look it up (rather than turning it into a method).
+            # This makes sure our URL reversing works ok.      
+            initkwargs['resource'].view_callable = (view,)
+        return view
+
 
 ########## Model Mixins ##########
 
diff --git a/djangorestframework/views.py b/djangorestframework/views.py
index 2e7e8418..81567e68 100644
--- a/djangorestframework/views.py
+++ b/djangorestframework/views.py
@@ -11,7 +11,7 @@ __all__ = (
     'BaseView',
     'ModelView',
     'InstanceModelView',
-    'ListOrModelView',
+    'ListModelView',
     'ListOrCreateModelView'
 )
 
@@ -131,7 +131,3 @@ class ListModelView(ListModelMixin, ModelView):
 class ListOrCreateModelView(ListModelMixin, CreateModelMixin, ModelView):
     """A view which provides default operations for list and create, against a model in the database."""
     pass
-
-
-
-
diff --git a/docs/conf.py b/docs/conf.py
index 1a87b024..503b4059 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -60,6 +60,7 @@ version = '0.1'
 release = '0.1'
 
 autodoc_member_order='bysource'
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst
index 07f7cbc5..9d762f52 100644
--- a/docs/examples/blogpost.rst
+++ b/docs/examples/blogpost.rst
@@ -27,7 +27,7 @@ Creating the resources
 Once we have some existing models there's very little we need to do to create the corresponding resources.  We simply create a base resource and an instance resource for each model we're working with.
 django-rest-framework will provide the default operations on the resources all the usual input validation that Django's models can give us for free.
 
-``views.py``
+#``views.py``
 
-.. include:: ../../examples/blogpost/views.py
-    :literal:
\ No newline at end of file
+#.. include:: ../../examples/blogpost/views.py
+#   :literal:
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 4da2da1c..3b4e9c49 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,7 +18,7 @@ Features:
 * Automatically provides an awesome Django admin style `browse-able self-documenting API <http://api.django-rest-framework.org>`_.
 * Clean, simple, views for Resources, using Django's new `class based views <http://docs.djangoproject.com/en/dev/topics/class-based-views/>`_.
 * Support for ModelResources with out-of-the-box default implementations and input validation.
-* Pluggable :mod:`.emitters`, :mod:`parsers`, :mod:`validators` and :mod:`authenticators` - Easy to customise.
+* Pluggable :mod:`.parsers`, :mod:`renderers`, :mod:`authentication` and :mod:`permissions` - Easy to customise.
 * Content type negotiation using HTTP Accept headers.
 * Optional support for forms as input validation.
 * Modular architecture - MixIn classes can be used without requiring the :class:`.Resource` or :class:`.ModelResource` classes.
@@ -36,7 +36,8 @@ Resources
 
 Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*.
 
-We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking!  (See: `Bitbucket <http://confluence.atlassian.com/display/BITBUCKET/Forking+a+Bitbucket+Repository>`_, `GitHub <http://help.github.com/fork-a-repo/>`_)
+We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking!  (See: `Forking a Bitbucket Repository 
+<http://confluence.atlassian.com/display/BITBUCKET/Forking+a+Bitbucket+Repository>`_, or `Fork A GitHub Repo <http://help.github.com/fork-a-repo/>`_)
 
 Requirements
 ------------
@@ -139,14 +140,16 @@ Library Reference
 .. toctree::
   :maxdepth: 1
 
-  library/resource
-  library/modelresource
-  library/emitters
+  library/authentication
+  library/compat
+  library/mixins
   library/parsers
-  library/authenticators
-  library/validators
+  library/permissions
+  library/renderers
+  library/resource
   library/response
   library/status
+  library/views
 
 Examples Reference
 ------------------
diff --git a/docs/library/authentication.rst b/docs/library/authentication.rst
new file mode 100644
index 00000000..d159f605
--- /dev/null
+++ b/docs/library/authentication.rst
@@ -0,0 +1,5 @@
+:mod:`authentication`
+=====================
+
+.. automodule:: authentication
+   :members:
diff --git a/docs/library/authenticators.rst b/docs/library/authenticators.rst
deleted file mode 100644
index 407339f7..00000000
--- a/docs/library/authenticators.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-:mod:`authenticators`
-=====================
-
-.. automodule:: authenticators
-   :members:
diff --git a/docs/library/compat.rst b/docs/library/compat.rst
new file mode 100644
index 00000000..93fb081a
--- /dev/null
+++ b/docs/library/compat.rst
@@ -0,0 +1,5 @@
+:mod:`compat`

+=====================

+

+.. automodule:: compat

+   :members:

diff --git a/docs/library/emitters.rst b/docs/library/emitters.rst
deleted file mode 100644
index 590ace0f..00000000
--- a/docs/library/emitters.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-:mod:`emitters`
-===============
-
-The emitters module provides a set of emitters that can be plugged in to a :class:`.Resource`.  An emitter is responsible for taking the output of a and serializing it to a given media type.  A :class:`.Resource` can have a number of emitters, allow the same content to be serialized in a number of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header.
-
-.. automodule:: emitters
-   :members:
diff --git a/docs/library/mixins.rst b/docs/library/mixins.rst
new file mode 100644
index 00000000..04bf66b0
--- /dev/null
+++ b/docs/library/mixins.rst
@@ -0,0 +1,5 @@
+:mod:`mixins`

+=====================

+

+.. automodule:: mixins

+   :members:

diff --git a/docs/library/modelresource.rst b/docs/library/modelresource.rst
deleted file mode 100644
index af760944..00000000
--- a/docs/library/modelresource.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-:mod:`modelresource`
-====================
-
-.. note::
-
-    TODO - document this module properly
-
-.. automodule:: modelresource
-   :members:
diff --git a/docs/library/permissions.rst b/docs/library/permissions.rst
new file mode 100644
index 00000000..c694d639
--- /dev/null
+++ b/docs/library/permissions.rst
@@ -0,0 +1,5 @@
+:mod:`permissions`

+=====================

+

+.. automodule:: permissions

+   :members:

diff --git a/docs/library/renderers.rst b/docs/library/renderers.rst
new file mode 100644
index 00000000..a9e72931
--- /dev/null
+++ b/docs/library/renderers.rst
@@ -0,0 +1,10 @@
+:mod:`renderers`
+================
+
+The renderers module provides a set of renderers that can be plugged in to a :class:`.Resource`.  
+A renderer is responsible for taking the output of a View and serializing it to a given media type.  
+A :class:`.Resource` can have a number of renderers, allow the same content to be serialized in a number
+of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header.
+
+.. automodule:: renderers
+   :members:
diff --git a/docs/library/validators.rst b/docs/library/validators.rst
deleted file mode 100644
index 5d8b1dd7..00000000
--- a/docs/library/validators.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-:mod:`validators`
-=================
-
-.. automodule:: validators
-   :members:
diff --git a/docs/library/views.rst b/docs/library/views.rst
new file mode 100644
index 00000000..329b487b
--- /dev/null
+++ b/docs/library/views.rst
@@ -0,0 +1,5 @@
+:mod:`views`

+=====================

+

+.. automodule:: views

+   :members: