Merge Marko's doc improvements.

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. (*)
+        :param request: Request to be authenticated
+        :rtype: :obj:`User` or None [*]_
        
-        This function must be overridden to be implemented.
-        
-        (*) The authentication context _will_ typically be a ``User`` object,
+        .. [*] 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 ``User``.
+            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.

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 ##########
 

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
-
-
-
-

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

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:
+#.. include:: ../../examples/blogpost/views.py
+#   :literal:

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
 ------------------

docs/library/authentication.rst

@@ -0,0 +1,5 @@
+:mod:`authentication`
+=====================
+
+.. automodule:: authentication
+   :members:

docs/library/authenticators.rst

@@ -1,5 +0,0 @@
-:mod:`authenticators`
-=====================
-
-.. automodule:: authenticators
-   :members:

docs/library/compat.rst

@@ -0,0 +1,5 @@
+:mod:`compat`
+=====================
+
+.. automodule:: compat
+   :members:

docs/library/emitters.rst

@@ -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:

docs/library/mixins.rst

@@ -0,0 +1,5 @@
+:mod:`mixins`
+=====================
+
+.. automodule:: mixins
+   :members:

docs/library/modelresource.rst

@@ -1,9 +0,0 @@
-:mod:`modelresource`
-====================
-
-.. note::
-
-    TODO - document this module properly
-
-.. automodule:: modelresource
-   :members:

docs/library/permissions.rst

@@ -0,0 +1,5 @@
+:mod:`permissions`
+=====================
+
+.. automodule:: permissions
+   :members:

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:

docs/library/validators.rst

@@ -1,5 +0,0 @@
-:mod:`validators`
-=================
-
-.. automodule:: validators
-   :members:

docs/library/views.rst

@@ -0,0 +1,5 @@
+:mod:`views`
+=====================
+
+.. automodule:: views
+   :members: