Tweak parsers to take parser_context

8 files changed, 46 insertions, 36 deletions

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index ae21c66e..71f48163 100644
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -60,6 +60,8 @@ Or, if you're using the `@api_view` decorator with function based views.
         }
         return Response(content)
 
+# API Reference
+
 ## BasicAuthentication
 
 This policy uses [HTTP Basic Authentication][basicauth], signed against a user's username and password.  Basic authentication is generally only appropriate for testing.
@@ -113,7 +115,7 @@ If successfully authenticated, `SessionAuthentication` provides the following cr
 * `request.user` will be a `django.contrib.auth.models.User` instance.
 * `request.auth` will be `None`.
 
-## Custom authentication policies
+# Custom authentication
 
 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.
 
diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md
index c22d6d8b..c3bdb7b9 100644
--- a/docs/api-guide/exceptions.md
+++ b/docs/api-guide/exceptions.md
@@ -37,7 +37,7 @@ Might recieve an error response indicating that the `DELETE` method is not allow
 
 **Signature:** `APIException(detail=None)`
 
-The base class for all exceptions raised inside REST framework.
+The **base class** for all exceptions raised inside REST framework.
 
 To provide a custom exception, subclass `APIException` and set the `.status_code` and `.detail` properties on the class.
 
diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md
index 50be59bf..e416de02 100644
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@@ -100,7 +100,7 @@ You can also set the pagination style on a per-view basis, using the `ListAPIVie
 
 For more complex requirements such as serialization that differs depending on the requested media type you can override the `.get_paginate_by()` and `.get_pagination_serializer_class()` methods.
 
-## Creating custom pagination serializers
+## Custom pagination serializers
 
 To create a custom pagination serializer class you should override `pagination.BasePaginationSerializer` and set the fields that you want the serializer to return.
 
diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md
index 4b769672..4f145ba3 100644
--- a/docs/api-guide/parsers.md
+++ b/docs/api-guide/parsers.md
@@ -65,7 +65,7 @@ Parses `YAML` request content.
 
 Parses REST framework's default style of `XML` request content.
 
-Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, `SOAP`, and `XHTML`.
+Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
 
 If you are considering using `XML` for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.
 
@@ -95,7 +95,19 @@ To implement a custom parser, you should override `BaseParser`, set the `.media_
 
 The method should return the data that will be used to populate the `request.DATA` property.
 
-For example:
+The arguments passed to `.parse_stream()` are:
+
+### stream
+
+A stream-like object representing the body of the request.
+
+### parser_context
+
+If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content.  By default it includes the keys `'upload_handlers'` and `'meta'`, which contain the values of the `request.upload_handlers` and `request.meta` properties.
+
+## Example
+
+The following is an example plaintext parser that will populate the `request.DATA` property with a string representing the body of the request. 
 
     class PlainTextParser(BaseParser):
     """
@@ -110,16 +122,6 @@ For example:
         """
         return stream.read()
 
-The arguments passed to `.parse_stream()` are:
-
-### stream
-
-A stream-like object representing the body of the request.
-
-### parser_context
-
-If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content.  By default it includes the keys `'upload_handlers'` and `'meta'`, which contain the values of the `request.upload_handlers` and `request.meta` properties.
-
 ## Uploading file content
 
 If your custom parser needs to support file uploads, you may return a `DataAndFiles` object from the `.parse_stream()` method.  `DataAndFiles` should be instantiated with two arguments.  The first argument will be used to populate the `request.DATA` property, and the second argument will be used to populate the `request.FILES` property.
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md
index b6912d88..eb290849 100644
--- a/docs/api-guide/permissions.md
+++ b/docs/api-guide/permissions.md
@@ -54,6 +54,8 @@ Or, if you're using the `@api_view` decorator with function based views.
         }
         return Response(content)
 
+# API Reference
+
 ## IsAuthenticated
 
 The `IsAuthenticated` permission class will deny permission to any unauthenticated user, and allow permission otherwise.
@@ -86,7 +88,7 @@ To use custom model permissions, override `DjangoModelPermissions` and set the `
 
 The `DjangoModelPermissions` class also supports object-level permissions.  Third-party authorization backends such as [django-guardian][guardian] that provide object-level permissions should work just fine with `DjangoModelPermissions` without any custom configuration required.
 
-## Custom permissions
+# Custom permissions
 
 To implement a custom permission, override `BasePermission` and implement the `.has_permission(self, request, view, obj=None)` method.
 
diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md
index 024a4ee2..c8addb32 100644
--- a/docs/api-guide/renderers.md
+++ b/docs/api-guide/renderers.md
@@ -98,7 +98,7 @@ Renders the request data into `YAML`.
 
 Renders REST framework's default style of `XML` response content.
 
-Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, `SOAP`, and `XHTML`.
+Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
 
 If you are considering using `XML` for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.
 
@@ -154,21 +154,6 @@ Renders data into HTML for the Browseable API.  This renderer will determine whi
 
 To implement a custom renderer, you should override `BaseRenderer`, set the `.media_type` and `.format` properties, and implement the `.render(self, data, media_type=None, renderer_context=None)` method.
 
-For example:
-
-    from django.utils.encoding import smart_unicode
-    from rest_framework import renderers
-
-
-    class PlainText(renderers.BaseRenderer):
-        media_type = 'text/plain'
-        format = 'txt'
-        
-        def render(self, data, media_type=None, renderer_context=None):
-            if isinstance(data, basestring):
-                return data
-            return smart_unicode(data)
-
 The arguments passed to the `.render()` method are:
 
 ### `data`
@@ -184,6 +169,23 @@ Optional. If provided, this is the accepted media type, as determined by the con
 Optional. If provided, this is a dictionary of contextual information provided by the view.
 By default this will include the following keys: `view`, `request`, `response`, `args`, `kwargs`.
 
+## Example
+
+The following is an example plaintext renderer that will return a response with the `data` parameter as the content of the response.
+
+    from django.utils.encoding import smart_unicode
+    from rest_framework import renderers
+
+
+    class PlainText(renderers.BaseRenderer):
+        media_type = 'text/plain'
+        format = 'txt'
+        
+        def render(self, data, media_type=None, renderer_context=None):
+            if isinstance(data, basestring):
+                return data
+            return smart_unicode(data)
+
 ---
 
 # Advanced renderer usage
diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md
index 0e228905..3fb95ae3 100644
--- a/docs/api-guide/throttling.md
+++ b/docs/api-guide/throttling.md
@@ -63,6 +63,8 @@ Or, if you're using the `@api_view` decorator with function based views.
         }
         return Response(content)
 
+# API Reference
+
 ## AnonRateThrottle
 
 The `AnonThrottle` will only ever throttle unauthenticated users.  The IP address of the incoming request is used to generate a unique key to throttle against.
@@ -142,7 +144,7 @@ For example, given the following views...
 
 User requests to either `ContactListView` or `ContactDetailView` would be restricted to a total of 1000 requests per-day.  User requests to `UploadView` would be restricted to 20 requests per day.
 
-## Custom throttles
+# Custom throttles
 
 To create a custom throttle, override `BaseThrottle` and implement `.allow_request(request, view)`.  The method should return `True` if the request should be allowed, and `False` otherwise.
 
diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md
index b58dfcb7..dda10eb4 100644
--- a/docs/topics/rest-hypermedia-hateoas.md
+++ b/docs/topics/rest-hypermedia-hateoas.md
@@ -24,15 +24,15 @@ For a more thorough background, check out Klabnik's [Hypermedia API reading list
 
 REST framework is an agnositic Web API toolkit.  It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.
 
-### What REST framework *does* provide.
+## What REST framework *does* provide.
 
 It is self evident that REST framework makes it possible to build Hypermedia APIs.  The browseable API that it offers is built on HTML - the hypermedia language of the web.
 
 REST framework also includes [serialization] and [parser]/[renderer] components that make it easy to build appropriate media types, [hyperlinked relations][fields] for building well-connected systems, and great support for [content negotiation][conneg].
 
-### What REST framework *doesn't* provide.
+## What REST framework *doesn't* provide.
 
-What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks.  Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.
+What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks.  Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.
 
 [cite]: http://vimeo.com/channels/restfest/page:2
 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm