Merge master

7 files changed, 61 insertions, 19 deletions

diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md
index ed54a876..bbb9b73c 100644
--- a/docs/tutorial/1-serialization.md
+++ b/docs/tutorial/1-serialization.md
@@ -2,13 +2,13 @@
 
 ## Introduction
 
-This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together.
+This tutorial will cover creating a simple pastebin code highlighting Web API.  Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together.
 
 The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started.  If you just want a quick overview, you should head over to the [quickstart] documentation instead.
 
 ---
 
-**Note**: The code for this tutorial is available in the [tomchristie/rest-framework-tutorial][repo] repository on GitHub. The completed implementation is also online as a sandbox version for testing, [available here][sandbox].
+**Note**: The code for this tutorial is available in the [tomchristie/rest-framework-tutorial][repo] repository on GitHub.  The completed implementation is also online as a sandbox version for testing, [available here][sandbox].
 
 ---
 
@@ -73,7 +73,7 @@ Okay, we're ready to roll.
 
 ## Creating a model to work with
 
-For the purposes of this tutorial we're going to start by creating a simple `Snippet` model that is used to store code snippets.  Go ahead and edit the  `snippets` app's `models.py` file. Note: Good programming practices include comments. Although you will find them in our repository version of this tutorial code, we have omitted them here to focus on the code itself.
+For the purposes of this tutorial we're going to start by creating a simple `Snippet` model that is used to store code snippets.  Go ahead and edit the `snippets` app's `models.py` file.  Note: Good programming practices include comments.  Although you will find them in our repository version of this tutorial code, we have omitted them here to focus on the code itself.
 
     from django.db import models
     from pygments.lexers import get_all_lexers
@@ -146,6 +146,8 @@ The first thing we need to get started on our Web API is provide a way of serial
 
 The first part of serializer class defines the fields that get serialized/deserialized.  The `restore_object` method defines how fully fledged instances get created when deserializing data.
 
+Notice that we can also use various attributes that would typically be used on form fields, such as `widget=widgets.Testarea`.  These can be used to control how the serializer should render when displayed as an HTML form.  This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial.
+
 We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit.  
 
 ## Working with Serializers
@@ -293,7 +295,7 @@ We'll also need a view which corresponds to an individual snippet, and can be us
             snippet.delete()
             return HttpResponse(status=204)
 
-Finally we need to wire these views up. Create the `snippets/urls.py` file:
+Finally we need to wire these views up.  Create the `snippets/urls.py` file:
 
     from django.conf.urls import patterns, url
 
diff --git a/docs/tutorial/2-requests-and-responses.md b/docs/tutorial/2-requests-and-responses.md
index 3a002cb0..30966a10 100644
--- a/docs/tutorial/2-requests-and-responses.md
+++ b/docs/tutorial/2-requests-and-responses.md
@@ -8,7 +8,7 @@ Let's introduce a couple of essential building blocks.
 REST framework introduces a `Request` object that extends the regular `HttpRequest`, and provides more flexible request parsing.  The core functionality of the `Request` object is the `request.DATA` attribute, which is similar to `request.POST`, but more useful for working with Web APIs.
 
     request.POST  # Only handles form data.  Only works for 'POST' method.
-    request.DATA  # Handles arbitrary data.  Works any HTTP request with content.
+    request.DATA  # Handles arbitrary data.  Works for 'POST', 'PUT' and 'PATCH' methods.
 
 ## Response objects
 
@@ -98,7 +98,7 @@ Notice that we're no longer explicitly tying our requests or responses to a give
 
 ## Adding optional format suffixes to our URLs
 
-To take advantage of the fact that our responses are no longer hardwired to a single content type let's add support for format suffixes to our API endpoints. Using format suffixes gives us URLs that explicitly refer to a given format, and means our API will be able to handle URLs such as [http://example.com/api/items/4.json][json-url].
+To take advantage of the fact that our responses are no longer hardwired to a single content type let's add support for format suffixes to our API endpoints.  Using format suffixes gives us URLs that explicitly refer to a given format, and means our API will be able to handle URLs such as [http://example.com/api/items/4.json][json-url].
 
 Start by adding a `format` keyword argument to both of the views, like so.
 
@@ -158,7 +158,7 @@ Now go and open the API in a web browser, by visiting [http://127.0.0.1:8000/sni
 
 ### Browsability
 
-Because the API chooses the content type of the response based on the client request, it will, by default, return an HTML-formatted representation of the resource when that resource is requested by a web browser. This allows for the API to return a fully web-browsable HTML representation.
+Because the API chooses the content type of the response based on the client request, it will, by default, return an HTML-formatted representation of the resource when that resource is requested by a web browser.  This allows for the API to return a fully web-browsable HTML representation.
 
 Having a web-browsable API is a huge usability win, and makes developing and using your API much easier.  It also dramatically lowers the barrier-to-entry for other developers wanting to inspect and work with your API.
 
diff --git a/docs/tutorial/3-class-based-views.md b/docs/tutorial/3-class-based-views.md
index 70cf2c54..c1b3d8f2 100644
--- a/docs/tutorial/3-class-based-views.md
+++ b/docs/tutorial/3-class-based-views.md
@@ -102,7 +102,7 @@ Let's take a look at how we can compose our views by using the mixin classes.
         def post(self, request, *args, **kwargs):
             return self.create(request, *args, **kwargs)
 
-We'll take a moment to examine exactly what's happening here. We're building our view using `GenericAPIView`, and adding in `ListModelMixin` and `CreateModelMixin`.
+We'll take a moment to examine exactly what's happening here.  We're building our view using `GenericAPIView`, and adding in `ListModelMixin` and `CreateModelMixin`.
 
 The base class provides the core functionality, and the mixin classes provide the `.list()` and `.create()` actions.  We're then explicitly binding the `get` and `post` methods to the appropriate actions.  Simple enough stuff so far.
 
diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md
index f6c3efb0..393d879a 100644
--- a/docs/tutorial/4-authentication-and-permissions.md
+++ b/docs/tutorial/4-authentication-and-permissions.md
@@ -17,7 +17,7 @@ Add the following two fields to the model.
     owner = models.ForeignKey('auth.User', related_name='snippets')
     highlighted = models.TextField()
 
-We'd also need to make sure that when the model is saved, that we populate the highlighted field, using the `pygments` code higlighting library.
+We'd also need to make sure that when the model is saved, that we populate the highlighted field, using the `pygments` code highlighting library.
 
 We'll need some extra imports:
 
@@ -94,7 +94,7 @@ On **both** the `SnippetList` and `SnippetDetail` view classes, add the followin
 
 ## Updating our serializer
 
-Now that snippets are associated with the user that created them, let's update our `SnippetSerializer` to reflect that. Add the following field to the serializer definition:
+Now that snippets are associated with the user that created them, let's update our `SnippetSerializer` to reflect that.  Add the following field to the serializer definition:
 
     owner = serializers.Field(source='owner.username')
 
@@ -120,7 +120,7 @@ Then, add the following property to **both** the `SnippetList` and `SnippetDetai
 
 ## Adding login to the Browsable API
 
-If you open a browser and navigate to the browsable API at the moment, you'll find that you're no longer able to create new code snippets. In order to do so we'd need to be able to login as a user.
+If you open a browser and navigate to the browsable API at the moment, you'll find that you're no longer able to create new code snippets.  In order to do so we'd need to be able to login as a user.
 
 We can add a login view for use with the browsable API, by editing our URLconf once more.
 
@@ -137,7 +137,7 @@ And, at the end of the file, add a pattern to include the login and logout views
 
 The `r'^api-auth/'` part of pattern can actually be whatever URL you want to use.  The only restriction is that the included urls must use the `'rest_framework'` namespace.
 
-Now if you open up the browser again and refresh the page you'll see a 'Login' link in the top right of the page.  If you log in as one of the users you created earier, you'll be able to create code snippets again.
+Now if you open up the browser again and refresh the page you'll see a 'Login' link in the top right of the page.  If you log in as one of the users you created earlier, you'll be able to create code snippets again.
 
 Once you've created a few code snippets, navigate to the '/users/' endpoint, and notice that the representation includes a list of the snippet pks that are associated with each user, in each user's 'snippets' field.
 
diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md
index cb2e092c..2e013a94 100644
--- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md
+++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md
@@ -29,7 +29,7 @@ Unlike all our other API endpoints, we don't want to use JSON, but instead just
 
 The other thing we need to consider when creating the code highlight view is that there's no existing concrete generic view that we can use.  We're not returning an object instance, but instead a property of an object instance.
 
-Instead of using a concrete generic view, we'll use the base class for representing instances, and create our own `.get()` method. In your snippets.views add:
+Instead of using a concrete generic view, we'll use the base class for representing instances, and create our own `.get()` method.  In your snippets.views add:
 
     from rest_framework import renderers
     from rest_framework.response import Response
diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md
index 4b01d3e0..4ed10e82 100644
--- a/docs/tutorial/6-viewsets-and-routers.md
+++ b/docs/tutorial/6-viewsets-and-routers.md
@@ -1,4 +1,4 @@
-# Tutorial 6 - ViewSets & Routers
+# Tutorial 6: ViewSets & Routers
 
 REST framework includes an abstraction for dealing with `ViewSets`, that allows the developer to concentrate on modeling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions.
 
@@ -59,7 +59,7 @@ To see what's going on under the hood let's first explicitly create a set of vie
 
 In the `urls.py` file we bind our `ViewSet` classes into a set of concrete views.
 
-    from snippets.resources import SnippetResource, UserResource
+    from snippets.views import SnippetViewSet, UserViewSet
 
     snippet_list = SnippetViewSet.as_view({
         'get': 'list',
@@ -119,7 +119,7 @@ Registering the viewsets with the router is similar to providing a urlpattern.
 
 The `DefaultRouter` class we're using also automatically creates the API root view for us, so we can now delete the `api_root` method from our `views` module.
 
-## Trade-offs between views vs viewsets.
+## Trade-offs between views vs viewsets
 
 Using viewsets can be a really useful abstraction.  It helps ensure that URL conventions will be consistent across your API, minimizes the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf.
 
diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md
index 52fe3acf..f15e75c0 100644
--- a/docs/tutorial/quickstart.md
+++ b/docs/tutorial/quickstart.md
@@ -2,7 +2,43 @@
 
 We're going to create a simple API to allow admin users to view and edit the users and groups in the system.
 
-Create a new Django project, and start a new app called `quickstart`.  Once you've set up a database and got everything synced and ready to go open up the app's directory and we'll get coding...
+## Project setup
+
+Create a new Django project named `tutorial`, then start a new app called `quickstart`.
+
+    # Set up a new project
+    django-admin.py startproject tutorial
+    cd tutorial
+
+    # Create a virtualenv to isolate our package dependencies locally
+    virtualenv env
+    source env/bin/activate
+
+    # Install Django and Django REST framework into the virtualenv
+    pip install django
+    pip install djangorestframework
+
+    # Create a new app
+    python manage.py startapp quickstart
+
+Next you'll need to get a database set up and synced.  If you just want to use SQLite for now, then you'll want to edit your `tutorial/settings.py` module to include something like this:
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.sqlite3',
+            'NAME': 'database.sql',
+            'USER': '',
+            'PASSWORD': '',
+            'HOST': '',
+            'PORT': ''
+        }
+    }
+
+The run `syncdb` like so:
+
+    python manage.py syncdb
+
+Once you've set up a database and got everything synced and ready to go, open up the app's directory and we'll get coding...
 
 ## Serializers
 
@@ -55,7 +91,7 @@ We can easily break these down into individual views if we need to, but using vi
 
 ## URLs
 
-Okay, now let's wire up the API URLs.  On to `quickstart/urls.py`...
+Okay, now let's wire up the API URLs.  On to `tutorial/urls.py`...
 
     from django.conf.urls import patterns, url, include
     from rest_framework import routers
@@ -80,7 +116,7 @@ Finally, we're including default login and logout views for use with the browsab
 
 ## Settings
 
-We'd also like to set a few global settings.  We'd like to turn on pagination, and we want our API to only be accessible to admin users.
+We'd also like to set a few global settings.  We'd like to turn on pagination, and we want our API to only be accessible to admin users.  The settings module will be in `tutorial/settings.py`
 
     INSTALLED_APPS = (
         ...
@@ -98,6 +134,10 @@ Okay, we're done.
 
 ## Testing our API
 
+We're now ready to test the API we've built.  Let's fire up the server from the command line.
+
+    python ./manage.py runserver
+
 We can now access our API, both from the command-line, using tools like `curl`...
 
     bash: curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/