20 files changed, 237 insertions, 57 deletions

diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md
index 5d6e0d91..f30b16ed 100755
--- a/docs/api-guide/authentication.md
+++ b/docs/api-guide/authentication.md
@@ -46,6 +46,11 @@ The default authentication schemes may be set globally, using the `DEFAULT_AUTHE
 You can also set the authentication scheme on a per-view or per-viewset basis,
 using the `APIView` class based views.
 
+    from rest_framework.authentication import SessionAuthentication, BasicAuthentication
+    from rest_framework.permissions import IsAuthenticated
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class ExampleView(APIView):
         authentication_classes = (SessionAuthentication, BasicAuthentication)
         permission_classes = (IsAuthenticated,)
@@ -121,7 +126,7 @@ To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in y
         'rest_framework.authtoken'
     )
     
-Make sure to run `manage.py syncdb` after changing your settings.
+Make sure to run `manage.py syncdb` after changing your settings. The `authtoken` database tables are managed by south (see [Schema migrations](#schema-migrations) below).
 
 You'll also need to create tokens for your users.
 
@@ -157,11 +162,16 @@ The `curl` command line tool may be useful for testing token authenticated APIs.
 
 If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal.
 
+    from django.dispatch import receiver
+    from rest_framework.authtoken.models import Token
+
     @receiver(post_save, sender=User)
     def create_auth_token(sender, instance=None, created=False, **kwargs):
         if created:
             Token.objects.create(user=instance)
 
+Note that you'll want to ensure you place this code snippet in an installed `models.py` module, or some other location that will be imported by Django on startup.
+
 If you've already created some users, you can generate tokens for all existing users like this:
 
     from django.contrib.auth.models import User
@@ -184,9 +194,11 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a
 
 Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings.  If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead.
 
-#### Custom user models
+#### Schema migrations
 
-The `rest_framework.authtoken` app includes a south migration that will create the authtoken table.   If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
+The `rest_framework.authtoken` app includes a south migration that will create the authtoken table.
+
+If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
 
 You can do so by inserting a `needed_by` attribute in your user migration:
 
@@ -201,6 +213,12 @@ You can do so by inserting a `needed_by` attribute in your user migration:
 
 For more details, see the [south documentation on dependencies][south-dependencies].
 
+Also note that if you're using a `post_save` signal to create tokens, then the first time you create the database tables, you'll need to ensure any migrations are run prior to creating any superusers.  For example:
+
+    python manage.py syncdb --noinput  # Won't create a superuser just yet, due to `--noinput`.
+    python manage.py migrate
+    python manage.py createsuperuser
+
 ## SessionAuthentication
 
 This authentication scheme 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.
@@ -328,6 +346,10 @@ If the `.authenticate_header()` method is not overridden, the authentication sch
 
 The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X_USERNAME'.
 
+	from django.contrib.auth.models import User
+    from rest_framework import authentication
+    from rest_framework import exceptions
+
     class ExampleAuthentication(authentication.BaseAuthentication):
         def authenticate(self, request):
             username = request.META.get('X_USERNAME')
diff --git a/docs/api-guide/content-negotiation.md b/docs/api-guide/content-negotiation.md
index 2a774278..94dd59ca 100644
--- a/docs/api-guide/content-negotiation.md
+++ b/docs/api-guide/content-negotiation.md
@@ -54,6 +54,8 @@ The `select_renderer()` method should return a two-tuple of (renderer instance,
 The following is a custom content negotiation class which ignores the client
 request when selecting the appropriate parser or renderer.
 
+    from rest_framework.negotiation import BaseContentNegotiation
+
     class IgnoreClientContentNegotiation(BaseContentNegotiation):
         def select_parser(self, request, parsers):
             """
@@ -77,6 +79,10 @@ The default content negotiation class may be set globally, using the `DEFAULT_CO
 
 You can also set the content negotiation used for an individual view, or viewset, using the `APIView` class based views.
 
+	from myapp.negotiation import IgnoreClientContentNegotiation
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class NoNegotiationView(APIView):
         """
         An example view that does not perform content negotiation.
diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md
index d69730c9..962c49e2 100644
--- a/docs/api-guide/fields.md
+++ b/docs/api-guide/fields.md
@@ -78,6 +78,9 @@ A generic, **read-only** field.  You can use this field for any attribute that d
 
 For example, using the following model.
 
+    from django.db import models
+    from django.utils.timezone import now
+
     class Account(models.Model):
         owner = models.ForeignKey('auth.user')
         name = models.CharField(max_length=100)
@@ -85,13 +88,14 @@ For example, using the following model.
         payment_expiry = models.DateTimeField()
         
         def has_expired(self):
-            now = datetime.datetime.now()
-            return now > self.payment_expiry
+            return now() > self.payment_expiry
 
 A serializer definition that looked like this:
 
+    from rest_framework import serializers
+
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
-        expired = Field(source='has_expired')
+        expired = serializers.Field(source='has_expired')
         
         class Meta:
             fields = ('url', 'owner', 'name', 'expired')
@@ -125,12 +129,11 @@ The `ModelField` class is generally intended for internal use, but can be used b
 
 This is a read-only field.  It gets its value by calling a method on the serializer class it is attached to.  It can be used to add any sort of data to the serialized representation of your object.  The field's constructor accepts a single argument, which is the name of the method on the serializer to be called.  The method should accept a single argument (in addition to `self`), which is the object being serialized.  It should return whatever you want to be included in the serialized representation of the object.  For example:
 
-    from rest_framework import serializers
     from django.contrib.auth.models import User
     from django.utils.timezone import now
+    from rest_framework import serializers
 
     class UserSerializer(serializers.ModelSerializer):
-
         days_since_joined = serializers.SerializerMethodField('get_days_since_joined')
 
         class Meta:
diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md
index 05c997a3..649462da 100644
--- a/docs/api-guide/filtering.md
+++ b/docs/api-guide/filtering.md
@@ -20,6 +20,10 @@ You can do so by filtering based on the value of `request.user`.
 
 For example:
 
+    from myapp.models import Purchase
+    from myapp.serializers import PurchaseSerializer
+    from rest_framework import generics
+
     class PurchaseList(generics.ListAPIView)
         serializer_class = PurchaseSerializer
  
@@ -90,6 +94,11 @@ The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKE
 You can also set the filter backends on a per-view, or per-viewset basis,
 using the `GenericAPIView` class based views.
 
+    from django.contrib.auth.models import User
+	from myapp.serializers import UserSerializer
+    from rest_framework import filters
+	from rest_framework import generics
+
     class UserListView(generics.ListAPIView):
         queryset = User.objects.all()
         serializer = UserSerializer
@@ -150,6 +159,11 @@ This will automatically create a `FilterSet` class for the given fields, and wil
 
 For more advanced filtering requirements you can specify a `FilterSet` class that should be used by the view.  For example:
 
+    import django_filters
+    from myapp.models import Product
+    from myapp.serializers import ProductSerializer
+    from rest_framework import generics
+
     class ProductFilter(django_filters.FilterSet):
         min_price = django_filters.NumberFilter(lookup_type='gte')
         max_price = django_filters.NumberFilter(lookup_type='lte')
diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md
index 67853ed0..931cae54 100755
--- a/docs/api-guide/generic-views.md
+++ b/docs/api-guide/generic-views.md
@@ -17,6 +17,11 @@ If the generic views don't suit the needs of your API, you can drop down to usin
 
 Typically when using the generic views, you'll override the view, and set several class attributes.
 
+    from django.contrib.auth.models import User
+    from myapp.serializers import UserSerializer
+	from rest_framework import generics
+	from rest_framework.permissions import IsAdminUser
+
     class UserList(generics.ListCreateAPIView):
         queryset = User.objects.all()
         serializer_class = UserSerializer
@@ -40,7 +45,7 @@ For more complex cases you might also want to override various methods on the vi
 
 For very simple cases you might want to pass through any class attributes using the `.as_view()` method.  For example, your URLconf might include something the following entry.
 
-    url(r'^/users/', ListCreateAPIView.as_view(model=User) name='user-list')
+    url(r'^/users/', ListCreateAPIView.as_view(model=User), name='user-list')
 
 ---
 
@@ -108,7 +113,12 @@ For example:
         filter = {}
         for field in self.multiple_lookup_fields:
             filter[field] = self.kwargs[field]
-        return get_object_or_404(queryset, **filter)
+
+        obj = get_object_or_404(queryset, **filter)
+        self.check_object_permissions(self.request, obj)
+        return obj
+
+Note that if your API doesn't include any object level permissions, you may optionally exclude the ``self.check_object_permissions, and simply return the object from the `get_object_or_404` lookup.
 
 #### `get_serializer_class(self)`
 
diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md
index 912ce41b..ca0174b7 100644
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@@ -13,6 +13,7 @@ REST framework includes a `PaginationSerializer` class that makes it easy to ret
 Let's start by taking a look at an example from the Django documentation.
 
     from django.core.paginator import Paginator
+
     objects = ['john', 'paul', 'george', 'ringo']
     paginator = Paginator(objects, 2)
     page = paginator.page(1)
@@ -22,6 +23,7 @@ Let's start by taking a look at an example from the Django documentation.
 At this point we've got a page object.  If we wanted to return this page object as a JSON response, we'd need to provide the client with context such as next and previous links, so that it would be able to page through the remaining results.
 
     from rest_framework.pagination import PaginationSerializer
+
     serializer = PaginationSerializer(instance=page)
     serializer.data
     # {'count': 4, 'next': '?page=2', 'previous': None, 'results': [u'john', u'paul']}
@@ -114,6 +116,9 @@ You can also override the name used for the object list field, by setting the `r
 
 For example, to nest a pair of links labelled 'prev' and 'next', and set the name for the results field to 'objects', you might use something like this.
 
+    from rest_framework import pagination
+    from rest_framework import serializers
+
     class LinksSerializer(serializers.Serializer):
         next = pagination.NextPageField(source='*')
         prev = pagination.PreviousPageField(source='*')
@@ -135,7 +140,7 @@ To have your custom pagination serializer be used by default, use the `DEFAULT_P
 
 Alternatively, to set your custom pagination serializer on a per-view basis, use the `pagination_serializer_class` attribute on a generic class based view:
 
-    class PaginatedListView(ListAPIView):
+    class PaginatedListView(generics.ListAPIView):
         model = ExampleModel
         pagination_serializer_class = CustomPaginationSerializer
         paginate_by = 10
diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md
index 5bd79a31..1030fcb6 100644
--- a/docs/api-guide/parsers.md
+++ b/docs/api-guide/parsers.md
@@ -34,9 +34,13 @@ The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSE
         )
     }
 
-You can also set the renderers used for an individual view, or viewset,
+You can also set the parsers used for an individual view, or viewset,
 using the `APIView` class based views.
 
+	from rest_framework.parsers import YAMLParser
+	from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class ExampleView(APIView):
         """
         A view that can accept POST requests with YAML content.
diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md
index 2c0a055c..12aa4c18 100644
--- a/docs/api-guide/permissions.md
+++ b/docs/api-guide/permissions.md
@@ -25,9 +25,17 @@ Object level permissions are run by REST framework's generic views when `.get_ob
 As with view level permissions, an `exceptions.PermissionDenied` exception will be raised if the user is not allowed to act on the given object.
 
 If you're writing your own views and want to enforce object level permissions,
-you'll need to explicitly call the `.check_object_permissions(request, obj)` method on the view at the point at which you've retrieved the object.
+or if you override the `get_object` method on a generic view, then you'll need to explicitly call the `.check_object_permissions(request, obj)` method on the view at the point at which you've retrieved the object.
+
 This will either raise a `PermissionDenied` or `NotAuthenticated` exception, or simply return if the view has the appropriate permissions.
 
+For example:
+
+    def get_object(self):
+        obj = get_object_or_404(self.get_queryset())
+        self.check_object_permissions(self.request, obj)
+        return obj
+
 ## Setting the permission policy
 
 The default permission policy may be set globally, using the `DEFAULT_PERMISSION_CLASSES` setting.  For example.
@@ -47,6 +55,10 @@ If not specified, this setting defaults to allowing unrestricted access:
 You can also set the authentication policy on a per-view, or per-viewset basis,
 using the `APIView` class based views.
 
+    from rest_framework.permissions import IsAuthenticated
+	from rest_framework.responses import Response
+	from rest_framework.views import APIView
+
     class ExampleView(APIView):
         permission_classes = (IsAuthenticated,)
 
@@ -147,7 +159,7 @@ If you need to test if a request is a read operation or a write operation, you s
 
 **Note**: In versions 2.0 and 2.1, the signature for the permission checks always included an optional `obj` parameter, like so: `.has_permission(self, request, view, obj=None)`.  The method would be called twice, first for the global permission checks, with no object supplied, and second for the object-level check when required.
 
-As of version 2.2 this signature has now been replaced with two separate method calls, which is more explict and obvious.  The old style signature continues to work, but it's use will result in a `PendingDeprecationWarning`, which is silent by default.  In 2.3 this will be escalated to a `DeprecationWarning`, and in 2.4 the old-style signature will be removed.
+As of version 2.2 this signature has now been replaced with two separate method calls, which is more explicit and obvious.  The old style signature continues to work, but its use will result in a `PendingDeprecationWarning`, which is silent by default.  In 2.3 this will be escalated to a `DeprecationWarning`, and in 2.4 the old-style signature will be removed.
 
 For more details see the [2.2 release announcement][2.2-announcement].
 
@@ -157,6 +169,8 @@ For more details see the [2.2 release announcement][2.2-announcement].
 
 The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted.
 
+    from rest_framework import permissions
+
     class BlacklistPermission(permissions.BasePermission):
         """
         Global permission check for blacklisted IPs.
@@ -188,6 +202,16 @@ Note that the generic views will check the appropriate object level permissions,
 
 Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance.  If you require object-level filtering of list views, you'll need to filter the queryset separately.  See the [filtering documentation][filtering] for more details.
 
+---
+
+# Third party packages
+
+The following third party packages are also available.
+
+## DRF Any Permissions
+
+The [DRF Any Permissions][drf-any-permissions] packages provides a different permission behavior in contrast to REST framework.  Instead of all specified permissions being required, only one of the given permissions has to be true in order to get access to the view.
+
 [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html
 [authentication]: authentication.md
 [throttling]: throttling.md
@@ -197,3 +221,4 @@ Also note that the generic views will only check the object-level permissions fo
 [django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider
 [2.2-announcement]: ../topics/2.2-announcement.md
 [filtering]: filtering.md
+[drf-any-permissions]: https://github.com/kevin-brown/drf-any-permissions
diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md
index 50c9bc54..aa14bc72 100644
--- a/docs/api-guide/relations.md
+++ b/docs/api-guide/relations.md
@@ -39,7 +39,7 @@ In order to explain the various types of relational fields, we'll use a couple o
 
 ## RelatedField
 
-`RelatedField` may be used to represent the target of the relationship using it's `__unicode__` method.
+`RelatedField` may be used to represent the target of the relationship using its `__unicode__` method.
 
 For example, the following serializer.
  
@@ -71,12 +71,12 @@ This field is read only.
 
 ## PrimaryKeyRelatedField
 
-`PrimaryKeyRelatedField` may be used to represent the target of the relationship using it's primary key.
+`PrimaryKeyRelatedField` may be used to represent the target of the relationship using its primary key.
 
 For example, the following serializer:
  
     class AlbumSerializer(serializers.ModelSerializer):
-        tracks = PrimaryKeyRelatedField(many=True, read_only=True)
+        tracks = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
         
         class Meta:
             model = Album
@@ -110,8 +110,8 @@ By default this field is read-write, although you can change this behavior using
 For example, the following serializer:
  
     class AlbumSerializer(serializers.ModelSerializer):
-        tracks = HyperlinkedRelatedField(many=True, read_only=True,
-                                         view_name='track-detail')
+        tracks = serializers.HyperlinkedRelatedField(many=True, read_only=True,
+                                                     view_name='track-detail')
         
         class Meta:
             model = Album
@@ -148,7 +148,8 @@ By default this field is read-write, although you can change this behavior using
 For example, the following serializer:
  
     class AlbumSerializer(serializers.ModelSerializer):
-        tracks = SlugRelatedField(many=True, read_only=True, slug_field='title')
+        tracks = serializers.SlugRelatedField(many=True, read_only=True,
+                                              slug_field='title')
         
         class Meta:
             model = Album
@@ -183,7 +184,7 @@ When using `SlugRelatedField` as a read-write field, you will normally want to e
 This field can be applied as an identity relationship, such as the `'url'` field on  a HyperlinkedModelSerializer.  It can also be used for an attribute on the object.  For example, the following serializer:
 
     class AlbumSerializer(serializers.HyperlinkedModelSerializer):
-        track_listing = HyperlinkedIdentityField(view_name='track-list')
+        track_listing = serializers.HyperlinkedIdentityField(view_name='track-list')
 
         class Meta:
             model = Album
@@ -252,7 +253,7 @@ If you want to implement a read-write relational field, you must also implement
 
 ## Example
 
-For, example, we could define a relational field, to serialize a track to a custom string representation, using it's ordering, title, and duration.
+For, example, we could define a relational field, to serialize a track to a custom string representation, using its ordering, title, and duration.
 
     import time
 
@@ -386,7 +387,7 @@ For more information see [the Django documentation on generic relations][generic
 By default, relational fields that target a ``ManyToManyField`` with a
 ``through`` model specified are set to read-only.
 
-If you exlicitly specify a relational field pointing to a
+If you explicitly specify a relational field pointing to a
 ``ManyToManyField`` with a through model, be sure to set ``read_only``
 to ``True``.
 
diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md
index 869bdc16..7fc1fc1f 100644
--- a/docs/api-guide/renderers.md
+++ b/docs/api-guide/renderers.md
@@ -30,11 +30,16 @@ The default set of renderers may be set globally, using the `DEFAULT_RENDERER_CL
 You can also set the renderers used for an individual view, or viewset,
 using the `APIView` class based views.
 
+    from django.contrib.auth.models import User
+    from rest_framework.renderers import JSONRenderer, YAMLRenderer
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
     class UserCountView(APIView):
         """
-        A view that returns the count of active users, in JSON or JSONp.
+        A view that returns the count of active users, in JSON or YAML.
         """
-        renderer_classes = (JSONRenderer, JSONPRenderer)
+        renderer_classes = (JSONRenderer, YAMLRenderer)
 
         def get(self, request, format=None):
             user_count = User.objects.filter(active=True).count()
@@ -217,6 +222,14 @@ Renders data into HTML for the Browsable API.  This renderer will determine whic
 
 **.charset**: `utf-8`
 
+#### Customizing BrowsableAPIRenderer
+
+By default the response content will be rendered with the highest priority renderer apart from `BrowseableAPIRenderer`.  If you need to customize this behavior, for example to use HTML as the default return format, but use JSON in the browsable API, you can do so by overriding the `get_default_renderer()` method.  For example:
+
+    class CustomBrowsableAPIRenderer(BrowsableAPIRenderer):
+        def get_default_renderer(self, view):
+            return JSONRenderer()
+
 ## MultiPartRenderer
 
 This renderer is used for rendering HTML multipart form data.  **It is not suitable as a response renderer**, but is instead used for creating test requests, using REST framework's [test client and test request factory][testing].
@@ -233,7 +246,7 @@ This renderer is used for rendering HTML multipart form data.  **It is not suita
 
 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.
 
-The method should return a bytestring, which wil be used as the body of the HTTP response.
+The method should return a bytestring, which will be used as the body of the HTTP response.
 
 The arguments passed to the `.render()` method are:
 
diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md
index 399b7c23..5a42aa92 100644
--- a/docs/api-guide/responses.md
+++ b/docs/api-guide/responses.md
@@ -24,7 +24,7 @@ Unless you want to heavily customize REST framework for some reason, you should
 
 Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content.  Instead you pass in unrendered data, which may consist of any Python primitives.
 
-The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object.
+The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primitive datatypes before creating the `Response` object.
 
 You can use REST framework's `Serializer` classes to perform this data serialization, or use your own custom serialization.
 
@@ -54,7 +54,7 @@ The rendered content of the response.  The `.render()` method must have been cal
 
 ## .template_name
 
-The `template_name`, if supplied.  Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the reponse.
+The `template_name`, if supplied.  Only required if `HTMLRenderer` or some other custom template renderer is the accepted renderer for the response.
 
 ## .accepted_renderer
 
diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md
index 19930dc3..383eca4c 100644
--- a/docs/api-guide/reverse.md
+++ b/docs/api-guide/reverse.md
@@ -17,7 +17,7 @@ The advantages of doing so are:
 
 REST framework provides two utility functions to make it more simple to return absolute URIs from your Web API.
 
-There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink it's output for you, which makes browsing the API much easier.
+There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
 
 ## reverse
 
@@ -27,13 +27,13 @@ Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except t
 
 You should **include the request as a keyword argument** to the function, for example:
 
-    import datetime
     from rest_framework.reverse import reverse
     from rest_framework.views import APIView
+	from django.utils.timezone import now
    
 	class APIRootView(APIView):
 	    def get(self, request):
-	        year = datetime.datetime.now().year
+	        year = now().year
 			data = {
  				...
     		    'year-summary-url': reverse('year-summary', args=[year], request=request)
diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md
index 86582905..fb48197e 100644
--- a/docs/api-guide/routers.md
+++ b/docs/api-guide/routers.md
@@ -14,6 +14,8 @@ REST framework adds support for automatic URL routing to Django, and provides yo
 
 Here's an example of a simple URL conf, that uses `DefaultRouter`.
 
+    from rest_framework import routers
+
     router = routers.SimpleRouter()
     router.register(r'users', UserViewSet)
     router.register(r'accounts', AccountViewSet)
@@ -38,7 +40,10 @@ The example above would generate the following URL patterns:
 ### Extra link and actions
 
 Any methods on the viewset decorated with `@link` or `@action` will also be routed.
-For example, a given method like this on the `UserViewSet` class:
+For example, given a method like this on the `UserViewSet` class:
+
+	from myapp.permissions import IsAdminOrIsSelf
+    from rest_framework.decorators import action
 
     @action(permission_classes=[IsAdminOrIsSelf])
     def set_password(self, request, pk=None):
@@ -66,7 +71,7 @@ This router includes routes for the standard set of `list`, `create`, `retrieve`
     <tr><td>POST</td><td>@action decorated method</td></tr>
 </table>
 
-By default the URLs created by `SimpleRouter` are appending with a trailing slash.
+By default the URLs created by `SimpleRouter` are appended with a trailing slash.
 This behavior can be modified by setting the `trailing_slash` argument to `False` when instantiating the router.  For example:
 
     router = SimpleRouter(trailing_slash=False)
@@ -90,13 +95,13 @@ This router is similar to `SimpleRouter` as above, but additionally includes a d
     <tr><td>POST</td><td>@action decorated method</td></tr>
 </table>
 
-As with `SimpleRouter` the trailing slashs on the URL routes can be removed by setting the `trailing_slash` argument to `False` when instantiating the router.
+As with `SimpleRouter` the trailing slashes on the URL routes can be removed by setting the `trailing_slash` argument to `False` when instantiating the router.
 
     router = DefaultRouter(trailing_slash=False)
 
 # Custom Routers
 
-Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are strutured.  Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
+Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are structured.  Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view.
 
 The simplest way to implement a custom router is to subclass one of the existing router classes.  The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples.
 
@@ -120,6 +125,8 @@ The arguments to the `Route` named tuple are:
 
 The following example will only route to the `list` and `retrieve` actions, and does not use the trailing slash convention.
 
+    from rest_framework.routers import Route, SimpleRouter
+
     class ReadOnlyRouter(SimpleRouter):
         """
         A router for read-only APIs, which doesn't use trailing slashes.
@@ -139,7 +146,7 @@ The `SimpleRouter` class provides another example of setting the `.routes` attri
 
 ## Advanced custom routers
 
-If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method.  The method should insect the registered viewsets and return a list of URL patterns.  The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute.  
+If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method.  The method should inspect the registered viewsets and return a list of URL patterns.  The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute.  
 
 You may also want to override the `get_default_base_name(self, viewset)` method, or else always explicitly set the `base_name` argument when registering your viewsets with the router.
 
diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index a1f0853e..d9fd4643 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -28,6 +28,8 @@ We'll declare a serializer that we can use to serialize and deserialize `Comment
 
 Declaring a serializer looks very similar to declaring a form:
 
+    from rest_framework import serializers
+
     class CommentSerializer(serializers.Serializer):
         email = serializers.EmailField()
         content = serializers.CharField(max_length=200)
@@ -59,6 +61,8 @@ We can now use `CommentSerializer` to serialize a comment, or list of comments.
 
 At this point we've translated the model instance into Python native datatypes.  To finalise the serialization process we render the data into `json`.
 
+    from rest_framework.renderers import JSONRenderer
+
     json = JSONRenderer().render(serializer.data)
     json
     # '{"email": "leila@example.com", "content": "foo bar", "created": "2012-08-22T16:20:09.822"}'
@@ -67,6 +71,9 @@ At this point we've translated the model instance into Python native datatypes.
         
 Deserialization is similar.  First we parse a stream into Python native datatypes... 
 
+    from StringIO import StringIO
+    from rest_framework.parsers import JSONParser
+
     stream = StringIO(json)
     data = JSONParser().parse(stream)
 
@@ -403,7 +410,7 @@ You can change the field that is used for object lookups by setting the `lookup_
 
 Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships.
 
-For more specfic requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly.  For example:
+For more specific requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly.  For example:
 
     class AccountSerializer(serializers.HyperlinkedModelSerializer):
         url = serializers.HyperlinkedIdentityField(
@@ -429,7 +436,7 @@ You can create customized subclasses of `ModelSerializer` or `HyperlinkedModelSe
 
 Doing so should be considered advanced usage, and will only be needed if you have some particular serializer requirements that you often need to repeat.
 
-## Dynamically modifiying fields
+## Dynamically modifying fields
 
 Once a serializer has been initialized, the dictionary of fields that are set on the serializer may be accessed using the `.fields` attribute.  Accessing and modifying this attribute allows you to dynamically modify the serializer.
 
@@ -449,7 +456,7 @@ For example, if you wanted to be able to set which fields should be used by a se
             # Don't pass the 'fields' arg up to the superclass
             fields = kwargs.pop('fields', None)
             
-            # Instatiate the superclass normally
+            # Instantiate the superclass normally
             super(DynamicFieldsModelSerializer, self).__init__(*args, **kwargs)
     
             if fields:
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index 7b114983..fe7925a5 100644
--- a/docs/api-guide/settings.md
+++ b/docs/api-guide/settings.md
@@ -28,7 +28,7 @@ you should use the `api_settings` object.  For example.
     
     print api_settings.DEFAULT_AUTHENTICATION_CLASSES
 
-The `api_settings` object will check for any user-defined settings, and otherwise fallback to the default values.  Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
+The `api_settings` object will check for any user-defined settings, and otherwise fall back to the default values.  Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
 
 ---
 
@@ -165,7 +165,7 @@ Default: `'multipart'`
 
 The renderer classes that are supported when building test requests.
 
-The format of any of these renderer classes may be used when contructing a test request, for example: `client.post('/users', {'username': 'jamie'}, format='json')`
+The format of any of these renderer classes may be used when constructing a test request, for example: `client.post('/users', {'username': 'jamie'}, format='json')`
 
 Default:
 
@@ -274,6 +274,40 @@ Default: `['iso-8601']`
 
 ---
 
+## View names and descriptions
+
+**The following settings are used to generate the view names and descriptions, as used in responses to `OPTIONS` requests, and as used in the browsable API.**
+
+#### VIEW_NAME_FUNCTION
+
+A string representing the function that should be used when generating view names.
+
+This should be a function with the following signature:
+
+    view_name(cls, suffix=None)
+
+* `cls`: The view class.  Typically the name function would inspect the name of the class when generating a descriptive name, by accessing `cls.__name__`.
+* `suffix`: The optional suffix used when differentiating individual views in a viewset.
+
+Default: `'rest_framework.views.get_view_name'`
+
+#### VIEW_DESCRIPTION_FUNCTION
+
+A string representing the function that should be used when generating view descriptions.
+
+This setting can be changed to support markup styles other than the default markdown.  For example, you can use it to support `rst` markup in your view docstrings being output in the browsable API.
+
+This should be a function with the following signature:
+
+    view_description(cls, html=False)
+
+* `cls`: The view class.  Typically the description function would inspect the docstring of the class when generating a description, by accessing `cls.__doc__`
+* `html`: A boolean indicating if HTML output is required.  `True` when used in the browsable API, and `False` when used in generating `OPTIONS` responses.
+
+Default: `'rest_framework.views.get_view_description'`
+
+---
+
 ## Miscellaneous settings
 
 #### FORMAT_SUFFIX_KWARG
diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md
index db2e059c..409f659b 100644
--- a/docs/api-guide/status-codes.md
+++ b/docs/api-guide/status-codes.md
@@ -9,6 +9,7 @@
 Using bare status codes in your responses isn't recommended.  REST framework includes a set of named constants that you can use to make more code more obvious and readable.
 
     from rest_framework import status
+    from rest_framework.response import Response
 
     def empty_view(self):
         content = {'please move along': 'nothing to see here'}
diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md
index 40b07763..35c1f766 100644
--- a/docs/api-guide/testing.md
+++ b/docs/api-guide/testing.md
@@ -2,7 +2,7 @@
 
 # Testing
 
-> Code without tests is broken as designed
+> Code without tests is broken as designed.
 >
 > &mdash; [Jacob Kaplan-Moss][cite]
 
@@ -16,6 +16,8 @@ Extends [Django's existing `RequestFactory` class][requestfactory].
 
 The `APIRequestFactory` class supports an almost identical API to Django's standard `RequestFactory` class.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.
 
+    from rest_framework.test import APIRequestFactory
+
     # Using the standard RequestFactory API to create a form POST request
     factory = APIRequestFactory()
     request = factory.post('/notes/', {'title': 'new idea'})
@@ -34,7 +36,7 @@ To support a wider set of request formats, or change the default format, [see th
 
 #### Explicitly encoding the request body
 
-If you need to explictly encode the request body, you can do so by setting the `content_type` flag.  For example:
+If you need to explicitly encode the request body, you can do so by setting the `content_type` flag.  For example:
 
     request = factory.post('/notes/', json.dumps({'title': 'new idea'}), content_type='application/json')
 
@@ -49,6 +51,8 @@ For example, using `APIRequestFactory`, you can make a form PUT request like so:
 
 Using Django's `RequestFactory`, you'd need to explicitly encode the data yourself:
 
+    from django.test.client import encode_multipart, RequestFactory
+
     factory = RequestFactory()
     data = {'title': 'remember to email dave'}
     content = encode_multipart('BoUnDaRyStRiNg', data)
@@ -72,6 +76,12 @@ To forcibly authenticate a request, use the `force_authenticate()` method.
 
 The signature for the method is `force_authenticate(request, user=None, token=None)`.  When making the call, either or both of the user and token may be set.
 
+For example, when forcibly authenticating using a token, you might do something like the following:
+
+    user = User.objects.get(username='olivia')
+    request = factory.get('/accounts/django-superstars/')
+    force_authenticate(request, user=user, token=user.token)
+
 ---
 
 **Note**: When using `APIRequestFactory`, the object that is returned is Django's standard `HttpRequest`, and not REST framework's `Request` object, which is only generated once the view is called.
@@ -105,6 +115,8 @@ Extends [Django's existing `Client` class][client].
 
 The `APIClient` class supports the same request interface as `APIRequestFactory`.  This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available.  For example:
 
+    from rest_framework.test import APIClient
+
     client = APIClient()
     client.post('/notes/', {'title': 'new idea'}, format='json')
 
@@ -131,8 +143,11 @@ The `login` method is appropriate for testing APIs that use session authenticati
 
 The `credentials` method can be used to set headers that will then be included on all subsequent requests by the test client.
 
+    from rest_framework.authtoken.models import Token
+    from rest_framework.test import APIClient
+
     # Include an appropriate `Authorization:` header on all requests.
-    token = Token.objects.get(username='lauren')
+    token = Token.objects.get(user__username='lauren')
     client = APIClient()
     client.credentials(HTTP_AUTHORIZATION='Token ' + token.key)
 
@@ -190,10 +205,10 @@ You can use any of REST framework's test case classes as you would for the regul
             Ensure we can create a new account object.
             """
             url = reverse('account-list')
-            data = {'name': 'DabApps'}
+            expected = {'name': 'DabApps'}
             response = self.client.post(url, data, format='json')
             self.assertEqual(response.status_code, status.HTTP_201_CREATED)
-            self.assertEqual(response.data, data)
+            self.assertEqual(response.data, expected)
 
 ---
 
diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md
index d6de85ba..42f9c228 100644
--- a/docs/api-guide/throttling.md
+++ b/docs/api-guide/throttling.md
@@ -12,7 +12,7 @@ As with permissions, multiple throttles may be used.  Your API might have a rest
 
 Another scenario where you might want to use multiple throttles would be if you need to impose different constraints on different parts of the API, due to some services being particularly resource-intensive.
 
-Multiple throttles can also be used if you want to impose both burst throttling  rates, and sustained throttling rates.  For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
+Multiple throttles can also be used if you want to impose both burst throttling rates, and sustained throttling rates.  For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
 
 Throttles do not necessarily only refer to rate-limiting requests.  For example a storage service might also need to throttle against bandwidth, and a paid data service might want to throttle against a certain number of a records being accessed.
 
@@ -43,8 +43,12 @@ The rate descriptions used in `DEFAULT_THROTTLE_RATES` may include `second`, `mi
 You can also set the throttling policy on a per-view or per-viewset basis,
 using the `APIView` class based views.
 
+	from rest_framework.response import Response
+    from rest_framework.throttling import UserRateThrottle
+	from rest_framework.views import APIView
+
     class ExampleView(APIView):
-        throttle_classes = (UserThrottle,)
+        throttle_classes = (UserRateThrottle,)
 
         def get(self, request, format=None):
             content = {
@@ -55,7 +59,7 @@ using the `APIView` class based views.
 Or, if you're using the `@api_view` decorator with function based views.
 
     @api_view('GET')
-    @throttle_classes(UserThrottle)
+    @throttle_classes(UserRateThrottle)
     def example_view(request, format=None):
         content = {
             'status': 'request was permitted'
@@ -72,22 +76,22 @@ The throttle classes provided by REST framework use Django's cache backend.  You
 
 ## 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.
+The `AnonRateThrottle` will only ever throttle unauthenticated users.  The IP address of the incoming request is used to generate a unique key to throttle against.
 
 The allowed request rate is determined from one of the following (in order of preference).
 
-* The `rate` property on the class, which may be provided by overriding `AnonThrottle` and setting the property.
+* The `rate` property on the class, which may be provided by overriding `AnonRateThrottle` and setting the property.
 * The `DEFAULT_THROTTLE_RATES['anon']` setting.
 
-`AnonThrottle` is suitable if you want to restrict the rate of requests from unknown sources.
+`AnonRateThrottle` is suitable if you want to restrict the rate of requests from unknown sources.
 
 ## UserRateThrottle
 
-The `UserThrottle` will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
+The `UserRateThrottle` will throttle users to a given rate of requests across the API.  The user id is used to generate a unique key to throttle against.  Unauthenticated requests will fall back to using the IP address of the incoming request to generate a unique key to throttle against.
 
 The allowed request rate is determined from one of the following (in order of preference).
 
-* The `rate` property on the class, which may be provided by overriding `UserThrottle` and setting the property.
+* The `rate` property on the class, which may be provided by overriding `UserRateThrottle` and setting the property.
 * The `DEFAULT_THROTTLE_RATES['user']` setting.
 
 An API may have multiple `UserRateThrottles` in place at the same time.  To do so, override `UserRateThrottle` and set a unique "scope" for each class.
@@ -113,11 +117,11 @@ For example, multiple user throttle rates could be implemented by using the foll
         }
     }
 
-`UserThrottle` is suitable if you want simple global rate restrictions per-user.
+`UserRateThrottle` is suitable if you want simple global rate restrictions per-user.
 
 ## ScopedRateThrottle
 
-The `ScopedThrottle` class can be used to restrict access to specific parts of the API.  This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property.  The unique throttle key will then be formed by concatenating the "scope" of the request with the unique user id or IP address.
+The `ScopedRateThrottle` class can be used to restrict access to specific parts of the API.  This throttle will only be applied if the view that is being accessed includes a `.throttle_scope` property.  The unique throttle key will then be formed by concatenating the "scope" of the request with the unique user id or IP address.
 
 The allowed request rate is determined by the `DEFAULT_THROTTLE_RATES` setting using a key from the request "scope".
 
diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md
index 683222d1..15581e09 100644
--- a/docs/api-guide/views.md
+++ b/docs/api-guide/views.md
@@ -110,7 +110,7 @@ You won't typically need to override this method.
 
 ### .finalize_response(self, request, response, \*args, **kwargs)
 
-Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotation.
+Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotiation.
 
 You won't typically need to override this method.
 
diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 0c68afb0..61f9d2f8 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -19,6 +19,12 @@ Typically, rather than explicitly registering the views in a viewset in the urlc
 
 Let's define a simple viewset that can be used to list or retrieve all the users in the system.
 
+    from django.contrib.auth.models import User
+    from django.shortcuts import get_object_or_404
+    from myapps.serializers import UserSerializer
+    from rest_framework import viewsets
+    from rest_framewor.responses import Response
+
     class UserViewSet(viewsets.ViewSet):
         """
         A simple ViewSet that for listing or retrieving users.
@@ -41,6 +47,9 @@ If we need to, we can bind this viewset into two separate views, like so:
 
 Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated.
 
+    from myapp.views import UserViewSet
+    from rest_framework.routers import DefaultRouter
+
     router = DefaultRouter()
     router.register(r'users', UserViewSet)
     urlpatterns = router.urls