Improve docs

5 files changed, 164 insertions, 8 deletions

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 76aaba8a..0a144a94 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -1,9 +1,88 @@
 # Authentication
 
+Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with.  The [permission] and [throttling] policies can then use those credentials to determine if the request should be permitted.
+
 REST framework provides a number of authentication policies out of the box, and also allows you to implement custom policies.
 
-## BasicAuthentication
+Authentication will run the first time either the `request.user` or `request.auth` properties are accessed, and determines how those properties are initialized.
+
+## Setting the authentication policy
+
+The default authentication policy may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting.  For example.
+
+    API_SETTINGS = {
+        'DEFAULT_AUTHENTICATION_CLASSES': (
+            'djangorestframework.authentication.SessionAuthentication',
+        )
+    }
+
+You can also set the authentication policy on a per-view basis, using the `APIView` class based views.
+
+    class ExampleView(APIView):
+        authentication_classes = (SessionAuthentication,)
+
+        def get(self, request, format=None):
+            content = {
+                'user': unicode(request.user),  # `django.contrib.auth.User` instance. 
+                'auth': unicode(request.auth),  # None
+            }
+            return Response(content)
+
+Or, if you're using the `@api_view` decorator with function based views.
+
+    @api_view(allowed=('GET',), authentication_classes=(SessionAuthentication,))
+    def example_view(request, format=None):
+        content = {
+            'user': unicode(request.user),  # `django.contrib.auth.User` instance. 
+            'auth': unicode(request.auth),  # None
+        }
+        return Response(content)
+
+## UserBasicAuthentication
+
+This policy uses [HTTP Basic Authentication][basicauth], signed against a user's username and password.  User basic authentication is generally only appropriate for testing.
+
+**Note:** If you run `UserBasicAuthentication` in production your API must be `https` only, or it will be completely insecure.  You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage.
+
+If successfully authenticated, `UserBasicAuthentication` provides the following credentials.
+
+* `request.user` will be a `django.contrib.auth.models.User` instance.
+* `request.auth` will be `None`.
 
 ## TokenBasicAuthentication
 
+This policy uses [HTTP Basic Authentication][basicauth], signed against a token key and secret.  Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients.
+
+**Note:** If you run `TokenBasicAuthentication` in production your API must be `https` only, or it will be completely insecure.
+
+If successfully authenticated, `TokenBasicAuthentication` provides the following credentials.
+
+* `request.user` will be a `django.contrib.auth.models.User` instance.
+* `request.auth` will be a `djangorestframework.models.BasicToken` instance.
+
+## OAuthAuthentication
+
+This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests.  OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf.
+
+If successfully authenticated, `OAuthAuthentication` provides the following credentials.
+
+* `request.user` will be a `django.contrib.auth.models.User` instance.
+* `request.auth` will be a `djangorestframework.models.OAuthToken` instance.
+
 ## SessionAuthentication
+
+This policy uses Django's default session backend for authentication.  Session authentication is appropriate for AJAX clients that are running in the same session context as your website.
+
+If successfully authenticated, `SessionAuthentication` provides the following credentials.
+
+* `request.user` will be a `django.contrib.auth.models.User` instance.
+* `request.auth` will be `None`.
+
+## Custom authentication policies
+
+To implement a custom authentication policy, subclass `BaseAuthentication` and override the `authenticate(self, request)` method.  The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.
+
+[basicauth]: http://tools.ietf.org/html/rfc2617
+[oauth]: http://oauth.net/2/
+[permission]: permissions.md
+[throttling]: throttling.md
\ No newline at end of file
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index c7bae30d..af8c4ec9 100644
--- a/docs/api-guide/settings.md
+++ b/docs/api-guide/settings.md
@@ -5,27 +5,89 @@ For example your project's `settings.py` file might look like this:
 
     API_SETTINGS = {
         'DEFAULT_RENDERERS': (
-            'djangorestframework.renderers.JSONRenderer',
             'djangorestframework.renderers.YAMLRenderer',
         )
         'DEFAULT_PARSERS': (
-            'djangorestframework.parsers.JSONParser',
             'djangorestframework.parsers.YAMLParser',
         )
     }
 
 ## DEFAULT_RENDERERS
 
-A list or tuple of renderer classes.
+A list or tuple of renderer classes, that determines the default set of renderers that may be used when returning a `Response` object.
 
 Default:
 
     (
-    'djangorestframework.renderers.JSONRenderer',
-    'djangorestframework.renderers.DocumentingHTMLRenderer')`
+        'djangorestframework.renderers.JSONRenderer',
+        'djangorestframework.renderers.DocumentingHTMLRenderer'
+        'djangorestframework.renderers.TemplateHTMLRenderer'
+    )
 
 ## DEFAULT_PARSERS
 
-A list or tuple of parser classes.
+A list or tuple of parser classes, that determines the default set of parsers used when accessing the `request.DATA` property.
+
+Default:
+
+    (
+        'djangorestframework.parsers.JSONParser',
+        'djangorestframework.parsers.FormParser'
+    )
+
+## DEFAULT_AUTHENTICATION
+
+A list or tuple of authentication classes, that determines the default set of authenticators used when accessing the `request.user` or `request.auth` properties.
+
+Default if `DEBUG` is `True`:
+
+    (
+        'djangorestframework.authentication.SessionAuthentication',
+        'djangorestframework.authentication.UserBasicAuthentication'
+    )
+
+Default if `DEBUG` is `False`:
+
+    (
+        'djangorestframework.authentication.SessionAuthentication',
+    )
+
+## DEFAULT_PERMISSIONS
+
+Default: `()`
+
+## DEFAULT_THROTTLES
 
 Default: `()`
+
+## DEFAULT_MODEL_SERIALIZER
+
+Default: `djangorestframework.serializers.ModelSerializer`
+
+## DEFAULT_PAGINATION_SERIALIZER
+
+Default: `djangorestframework.pagination.PaginationSerializer`
+
+## FORMAT_SUFFIX_KWARG
+
+Default: `format`
+
+## UNAUTHENTICATED_USER_CLASS
+
+Default: `django.contrib.auth.models.AnonymousUser`
+
+## FORM_METHOD_OVERRIDE
+
+Default: `_method`
+
+## FORM_CONTENT_OVERRIDE
+
+Default: `_content`
+
+## FORM_CONTENTTYPE_OVERRIDE
+
+Default: `_content_type`
+
+## URL_ACCEPT_OVERRIDE
+
+Default: `_accept`
diff --git a/docs/index.md b/docs/index.md
index 125efa79..72e247ee 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -91,6 +91,7 @@ General guides to using REST framework.
 
 * [CSRF][csrf]
 * [Form overloading][formoverloading]
+* [Contributing to REST framework][contributing]
 * [Credits][credits]
 
 ## Development
@@ -151,10 +152,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [permissions]: api-guide/permissions.md
 [throttling]: api-guide/throttling.md
 [exceptions]: api-guide/exceptions.md
-[status]: api-guide/status.md
+[status]: api-guide/status-codes.md
 [reverse]: api-guide/reverse.md
 [settings]: api-guide/settings.md
 
 [csrf]: topics/csrf.md
 [formoverloading]: topics/formoverloading.md
+[contributing]: topics/contributing.md
 [credits]: topics/credits.md
diff --git a/docs/template.html b/docs/template.html
index 2c3572e1..20b0afd4 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -103,6 +103,7 @@ margin-top: 5px;
                 <ul class="dropdown-menu">
                   <li><a href="{{ base_url }}/topics/csrf{{ suffix }}">Working with AJAX and CSRF</a></li>
                   <li><a href="{{ base_url }}/topics/formoverloading{{ suffix }}">Browser based PUT, PATCH and DELETE</a></li>
+                  <li><a href="{{ base_url }}/topics/contributing{{ suffix }}">Contributing to REST framework</a></li>
                   <li><a href="{{ base_url }}/topics/credits{{ suffix }}">Credits</a></li>
                 </ul>
               </li>
diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md
new file mode 100644
index 00000000..cbb41f2a
--- /dev/null
+++ b/docs/topics/contributing.md
@@ -0,0 +1,12 @@
+# Contributing to REST framework
+
+## Accessing settings
+
+**Describe api_settings**
+
+## Managing compatibility issues
+
+**Describe compat module**
+
+## Running the tests
+