7 files changed, 43 insertions, 33 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.