Update documentation

api-guide/fields/index.html

@@ -628,6 +628,7 @@ color_channel = serializers.ChoiceField(
 <h1 id="boolean-fields">Boolean fields</h1>
 <h2 id="booleanfield">BooleanField</h2>
 <p>A boolean representation.</p>
+<p>When using HTML encoded form input be aware that omitting a value will always be treated as setting a field to <code>False</code>, even if it has a <code>default=True</code> option specified. This is because HTML checkbox inputs represent the unchecked state by omitting the value, so REST framework treats omission as if it is an empty checkbox input.</p>
 <p>Corresponds to <code>django.db.models.fields.BooleanField</code>.</p>
 <p><strong>Signature:</strong> <code>BooleanField()</code></p>
 <h2 id="nullbooleanfield">NullBooleanField</h2>

api-guide/pagination/index.html

@@ -513,7 +513,7 @@ class LinksSerializer(serializers.Serializer):
 
 class CustomPaginationSerializer(pagination.BasePaginationSerializer):
     links = LinksSerializer(source='*')  # Takes the page object as the source
-    total_results = serializers.Field(source='paginator.count')
+    total_results = serializers.ReadOnlyField(source='paginator.count')
 
     results_field = 'objects'
 </code></pre>

api-guide/permissions/index.html

@@ -459,10 +459,19 @@
 </blockquote>
 <p>Together with <a href="../authentication">authentication</a> and <a href="../throttling">throttling</a>, permissions determine whether a request should be granted or denied access.</p>
 <p>Permission checks are always run at the very start of the view, before any other code is allowed to proceed.  Permission checks will typically use the authentication information in the <code>request.user</code> and <code>request.auth</code> properties to determine if the incoming request should be permitted.</p>
+<p>Permissions are used to grant or deny access different classes of users to different parts of the API.</p>
+<p>The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds the <code>IsAuthenticated</code> class in REST framework.</p>
+<p>A slightly less strict style of permission would be to allow full access to authenticated users, but allow read-only access to unauthenticated users. This corresponds to the <code>IsAuthenticatedOrReadOnly</code> class in REST framework.</p>
 <h2 id="how-permissions-are-determined">How permissions are determined</h2>
 <p>Permissions in REST framework are always defined as a list of permission classes.</p>
 <p>Before running the main body of the view each permission in the list is checked.
-If any permission check fails an <code>exceptions.PermissionDenied</code> exception will be raised, and the main body of the view will not run.</p>
+If any permission check fails an <code>exceptions.PermissionDenied</code> or <code>exceptions.NotAuthenticated</code> exception will be raised, and the main body of the view will not run.</p>
+<p>When the permissions checks fail either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules:</p>
+<ul>
+<li>The request was successfully authenticated, but permission was denied. <em>&mdash; An HTTP 403 Forbidden response will be returned.</em></li>
+<li>The request was not successfully authenticated, and the highest priority authentication class <em>does not</em> use <code>WWW-Authenticate</code> headers. <em>&mdash; An HTTP 403 Forbidden response will be returned.</em></li>
+<li>The request was not successfully authenticated, and the highest priority authentication class <em>does</em> use <code>WWW-Authenticate</code> headers. <em>&mdash; An HTTP 401 Unauthorized response, with an appropriate <code>WWW-Authenticate</code> header will be returned.</em></li>
+</ul>
 <h2 id="object-level-permissions">Object level permissions</h2>
 <p>REST framework permissions also support object-level permissioning.  Object level permissions are used to determine if a user should be allowed to act on a particular object, which will typically be a model instance.</p>
 <p>Object level permissions are run by REST framework's generic views when <code>.get_object()</code> is called.
@@ -526,7 +535,7 @@ def example_view(request, format=None):
 <p>This permission is suitable if you want your API to only be accessible to registered users.</p>
 <h2 id="isadminuser">IsAdminUser</h2>
 <p>The <code>IsAdminUser</code> permission class will deny permission to any user, unless <code>user.is_staff</code> is <code>True</code> in which case permission will be allowed.</p>
-<p>This permission is suitable is you want your API to only be accessible to a subset of trusted administrators.</p>
+<p>This permission is suitable if you want your API to only be accessible to a subset of trusted administrators.</p>
 <h2 id="isauthenticatedorreadonly">IsAuthenticatedOrReadOnly</h2>
 <p>The <code>IsAuthenticatedOrReadOnly</code> will allow authenticated users to perform any request.  Requests for unauthorised users will only be permitted if the request method is one of the "safe" methods; <code>GET</code>, <code>HEAD</code> or <code>OPTIONS</code>.</p>
 <p>This permission is suitable if you want to your API to allow read permissions to anonymous users, and only allow write permissions to authenticated users.</p>

api-guide/relations/index.html

@@ -792,7 +792,7 @@ class Note(models.Model):
             return 'Note: ' + value.text
         raise Exception('Unexpected type of tagged object')
 </code></pre>
-<p>If you need the target of the relationship to have a nested representation, you can use the required serializers inside the <code>.to_native()</code> method:</p>
+<p>If you need the target of the relationship to have a nested representation, you can use the required serializers inside the <code>.to_representation()</code> method:</p>
 <pre><code>    def to_representation(self, value):
         """
         Serialize bookmark instances using a bookmark serializer,

api-guide/routers/index.html

@@ -462,7 +462,7 @@ urlpatterns = router.urls
 </ul>
 <hr />
 <p><strong>Note</strong>: The <code>base_name</code> argument is used to specify the initial part of the view name pattern.  In the example above, that's the <code>user</code> or <code>account</code> part.</p>
-<p>Typically you won't <em>need</em> to specify the <code>base-name</code> argument, but if you have a viewset where you've defined a custom <code>get_queryset</code> method, then the viewset may not have a <code>.queryset</code> attribute set.  If you try to register that viewset you'll see an error like this:</p>
+<p>Typically you won't <em>need</em> to specify the <code>base_name</code> argument, but if you have a viewset where you've defined a custom <code>get_queryset</code> method, then the viewset may not have a <code>.queryset</code> attribute set.  If you try to register that viewset you'll see an error like this:</p>
 <pre><code>'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute.
 </code></pre>
 <p>This means you'll need to explicitly set the <code>base_name</code> argument when registering the viewset, as it could not be automatically determined from the model name.</p>

api-guide/serializers/index.html

@@ -370,6 +370,10 @@
                     </li>
                   
                     <li>
+                      <a href="#accessing-the-initial-data-and-instance">Accessing the initial data and instance</a>
+                    </li>
+                  
+                    <li>
                       <a href="#partial-updates">Partial updates</a>
                     </li>
                   
@@ -736,6 +740,9 @@ class GameRecord(serializers.Serializer):
         )
 </code></pre>
 <p>For more information see the <a href="../validators">validators documentation</a>.</p>
+<h2 id="accessing-the-initial-data-and-instance">Accessing the initial data and instance</h2>
+<p>When passing an initial object or queryset to a serializer instance, the object will be made available as <code>.instance</code>. If no initial object is passed then the <code>.instance</code> attribute will be <code>None</code>.</p>
+<p>When passing data to a serializer instance, the unmodified data will be made available as <code>.initial_data</code>. If the data keyword argument is not passed then the <code>.initial_data</code> attribute will not exist.</p>
 <h2 id="partial-updates">Partial updates</h2>
 <p>By default, serializers must be passed values for all required fields or they will raise validation errors. You can use the <code>partial</code> argument in order to allow partial updates.</p>
 <pre><code># Update `comment` with partial data

tutorial/1-serialization/index.html

@@ -535,7 +535,7 @@ content
 <p>Deserialization is similar.  First we parse a stream into Python native datatypes...</p>
 <pre><code># This import will use either `StringIO.StringIO` or `io.BytesIO`
 # as appropriate, depending on if we're running Python 2 or Python 3.
-from rest_framework.compat import BytesIO
+from django.utils.six import BytesIO
 
 stream = BytesIO(content)
 data = JSONParser().parse(stream)
@@ -565,7 +565,7 @@ Open the file <code>snippets/serializers.py</code> again, and edit the <code>Sni
         model = Snippet
         fields = ('id', 'title', 'code', 'linenos', 'language', 'style')
 </code></pre>
-<p>One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing it's representation. Open the Django shell with <code>python manange.py shell</code>, then try the following:</p>
+<p>One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing it's representation. Open the Django shell with <code>python manage.py shell</code>, then try the following:</p>
 <pre><code>&gt;&gt;&gt; from snippets.serializers import SnippetSerializer
 &gt;&gt;&gt; serializer = SnippetSerializer()
 &gt;&gt;&gt; print(repr(serializer))

tutorial/2-requests-and-responses/index.html

@@ -547,7 +547,7 @@ http --json POST http://127.0.0.1:8000/snippets/ code="print 456"
     "id": 4,
     "title": "",
     "code": "print 456",
-    "linenos": true,
+    "linenos": false,
     "language": "python",
     "style": "friendly"
 }

tutorial/quickstart/index.html

@@ -403,7 +403,7 @@ pip install django
 pip install djangorestframework
 
 # Set up a new project with a single application
-django-admin.py startproject tutorial .
+django-admin.py startproject tutorial .  # Note the trailing '.' character
 cd tutorial
 django-admin.py startapp quickstart
 cd ..