Merge master

Author: tomchristie

.gitignore

@@ -3,7 +3,7 @@
 *~
 .*
 
-html/
+site/
 htmlcov/
 coverage/
 build/

.travis.yml

@@ -4,6 +4,7 @@ sudo: false
 
 env:
     - TOX_ENV=py27-flake8
+    - TOX_ENV=py27-docs
     - TOX_ENV=py34-django17
     - TOX_ENV=py33-django17
     - TOX_ENV=py32-django17

CONTRIBUTING.md

@@ -101,15 +101,15 @@ There are many great markdown editors that make working with the documentation r
 
 ## Building the documentation
 
-To build the documentation, simply run the `mkdocs.py` script.
+To build the documentation, install MkDocs with `pip install mkdocs` and then run the following command.
 
-    ./mkdocs.py
+    mkdocs build
 
 This will build the html output into the `html` directory.
 
-You can build the documentation and open a preview in a browser window by using the `-p` flag.
+You can build the documentation and open a preview in a browser window by using the `serve` command.
 
-    ./mkdocs.py -p
+    mkdocs serve
 
 ## Language style
 

docs/CNAME

@@ -0,0 +1 @@
+www.django-rest-framework.org

docs/api-guide/authentication.md

@@ -1,4 +1,4 @@
-<a class="github" href="authentication.py"></a>
+source: authentication.py
 
 # Authentication
 

docs/api-guide/content-negotiation.md

@@ -1,4 +1,4 @@
-<a class="github" href="negotiation.py"></a>
+source: negotiation.py
 
 # Content negotiation
 
@@ -29,7 +29,7 @@ The priorities for each of the given media types would be:
 
 If the requested view was only configured with renderers for `YAML` and `HTML`, then REST framework would select whichever renderer was listed first in the `renderer_classes` list or `DEFAULT_RENDERER_CLASSES` setting.
 
-For more information on the `HTTP Accept` header, see [RFC 2616][accept-header] 
+For more information on the `HTTP Accept` header, see [RFC 2616][accept-header]
 
 ---
 
@@ -62,7 +62,7 @@ request when selecting the appropriate parser or renderer.
             Select the first parser in the `.parser_classes` list.
             """
             return parsers[0]
-        
+
         def select_renderer(self, request, renderers, format_suffix):
             """
             Select the first renderer in the `.renderer_classes` list.

docs/api-guide/exceptions.md

@@ -1,4 +1,4 @@
-<a class="github" href="exceptions.py"></a>
+source: exceptions.py
 
 # Exceptions
 

docs/api-guide/fields.md

@@ -1,4 +1,4 @@
-<a class="github" href="fields.py"></a>
+source: fields.py
 
 # Serializer fields
 

docs/api-guide/filtering.md

@@ -1,4 +1,4 @@
-<a class="github" href="filters.py"></a>
+source: filters.py
 
 # Filtering
 
@@ -26,7 +26,7 @@ For example:
 
     class PurchaseList(generics.ListAPIView):
         serializer_class = PurchaseSerializer
- 
+
         def get_queryset(self):
             """
             This view should return a list of all the purchases
@@ -38,7 +38,7 @@ For example:
 
 ## Filtering against the URL
 
-Another style of filtering might involve restricting the queryset based on some part of the URL.  
+Another style of filtering might involve restricting the queryset based on some part of the URL.
 
 For example if your URL config contained an entry like this:
 
@@ -48,7 +48,7 @@ You could then write a view that returned a purchase queryset filtered by the us
 
     class PurchaseList(generics.ListAPIView):
         serializer_class = PurchaseSerializer
- 
+
         def get_queryset(self):
             """
             This view should return a list of all the purchases for
@@ -57,15 +57,15 @@ You could then write a view that returned a purchase queryset filtered by the us
             username = self.kwargs['username']
             return Purchase.objects.filter(purchaser__username=username)
 
-## Filtering against query parameters 
+## Filtering against query parameters
 
 A final example of filtering the initial queryset would be to determine the initial queryset based on query parameters in the url.
 
 We can override `.get_queryset()` to deal with URLs such as `http://example.com/api/purchases?username=denvercoder9`, and filter the queryset only if the `username` parameter is included in the URL:
 
     class PurchaseList(generics.ListAPIView):
         serializer_class = PurchaseSerializer
- 
+
         def get_queryset(self):
             """
             Optionally restricts the returned purchases to a given user,
@@ -113,7 +113,7 @@ For instance, given the previous example, and a product with an id of `4675`, th
     http://example.com/api/products/4675/?category=clothing&max_price=10.00
 
 ## Overriding the initial queryset
- 
+
 Note that you can use both an overridden `.get_queryset()` and generic filtering together, and everything will work as expected.  For example, if `Product` had a many-to-many relationship with `User`, named `purchase`, you might want to write a view like this:
 
     class PurchasedProductsList(generics.ListAPIView):
@@ -124,7 +124,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering
         model = Product
         serializer_class = ProductSerializer
         filter_class = ProductFilter
-        
+
         def get_queryset(self):
             user = self.request.user
             return user.purchase_set.all()
@@ -135,7 +135,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering
 
 ## DjangoFilterBackend
 
-The `DjangoFilterBackend` class supports highly customizable field filtering, using the [django-filter package][django-filter].  
+The `DjangoFilterBackend` class supports highly customizable field filtering, using the [django-filter package][django-filter].
 
 To use REST framework's `DjangoFilterBackend`, first install `django-filter`.
 
@@ -216,15 +216,15 @@ This is nice, but it exposes the Django's double underscore convention as part o
 And now you can execute:
 
     http://example.com/api/products?manufacturer=foo
-    
+
 For more details on using filter sets see the [django-filter documentation][django-filter-docs].
 
 ---
 
 **Hints & Tips**
 
 * By default filtering is not enabled.  If you want to use `DjangoFilterBackend` remember to make sure it is installed by using the `'DEFAULT_FILTER_BACKENDS'` setting.
-* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`.  (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].) 
+* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`.  (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].)
 * `django-filter` supports filtering across relationships, using Django's double-underscore syntax.
 * For Django 1.3 support, make sure to install `django-filter` version 0.5.4, as later versions drop support for 1.3.
 
@@ -316,7 +316,7 @@ Typically you'd instead control this by setting `order_by` on the initial querys
         queryset = User.objects.all()
         serializer_class = UserSerializer
         filter_backends = (filters.OrderingFilter,)
-        ordering = ('username',) 
+        ordering = ('username',)
 
 The `ordering` attribute may be either a string or a list/tuple of strings.
 

docs/api-guide/format-suffixes.md

@@ -1,4 +1,4 @@
-<a class="github" href="urlpatterns.py"></a>
+source: urlpatterns.py
 
 # Format suffixes
 
@@ -7,7 +7,7 @@ used all the time.
 >
 > &mdash; Roy Fielding, [REST discuss mailing list][cite]
 
-A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type.  For example, 'http://example.com/api/users.json' to serve a JSON representation. 
+A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type.  For example, 'http://example.com/api/users.json' to serve a JSON representation.
 
 Adding format-suffix patterns to each individual entry in the URLconf for your API is error-prone and non-DRY, so REST framework provides a shortcut to adding these patterns to your URLConf.
 
@@ -21,7 +21,7 @@ Arguments:
 
 * **urlpatterns**: Required.  A URL pattern list.
 * **suffix_required**:  Optional.  A boolean indicating if suffixes in the URLs should be optional or mandatory.  Defaults to `False`, meaning that suffixes are optional by default.
-* **allowed**:  Optional.  A list or tuple of valid format suffixes.  If not provided, a wildcard format suffix pattern will be used. 
+* **allowed**:  Optional.  A list or tuple of valid format suffixes.  If not provided, a wildcard format suffix pattern will be used.
 
 Example:
 
@@ -33,7 +33,7 @@ Example:
         url(r'^comments/$', views.comment_list),
         url(r'^comments/(?P<pk>[0-9]+)/$', views.comment_detail)
     ]
-    
+
     urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
 
 When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views.  For example:
@@ -56,12 +56,12 @@ The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` se
 Also note that `format_suffix_patterns` does not support descending into `include` URL patterns.
 
 ---
-        
+
 ## Accept headers vs. format suffixes
 
 There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead.
 
-It is actually a misconception.  For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: 
+It is actually a misconception.  For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators:
 
 &ldquo;That's why I always prefer extensions.  Neither choice has anything to do with REST.&rdquo; &mdash; Roy Fielding, [REST discuss mailing list][cite2]