More updating docs for 0.2

--HG--
rename : docs/examples/modelresources.rst => docs/examples/modelviews.rst
rename : docs/examples/resources.rst => docs/examples/views.rst

docs/examples/blogpost.rst

@@ -8,26 +8,22 @@ Blog Posts API
 The models
 ----------
 
+In this example we're working from two related models:
+
 ``models.py``
 
 .. include:: ../../examples/blogpost/models.py
     :literal:
 
-URL configuration
+Creating the resources
------------------
+----------------------
+
+Once we have some existing models there's very little we need to do to create the API.
+Firstly create a resource for each model that defines which fields we want to expose on the model.
+Secondly we map a base view and an instance view for each resource.
+The generic views :class:`.ListOrCreateModelView` and :class:`.InstanceModelView` provide default operations for listing, creating and updating our models via the API, and also automatically provide input validation using default ModelForms for each model.
 
 ``urls.py``
 
 .. include:: ../../examples/blogpost/urls.py
     :literal:
-
-Creating the resources
-----------------------
-
-Once we have some existing models there's very little we need to do to create the corresponding resources.  We simply create a base resource and an instance resource for each model we're working with.
-django-rest-framework will provide the default operations on the resources all the usual input validation that Django's models can give us for free.
-
-#``views.py``
-
-#.. include:: ../../examples/blogpost/views.py
-#   :literal:

docs/examples/modelviews.rst

@@ -1,7 +1,7 @@
-.. _modelresources:
+.. _modelviews:
 
-Getting Started - Model Resources
+Getting Started - Model Views
----------------------------------
+-----------------------------
 
 .. note::
 
@@ -15,23 +15,23 @@ Getting Started - Model Resources
 
 Often you'll want parts of your API to directly map to existing django models.  Django REST framework handles this nicely for you in a couple of ways:
 
-#. It automatically provides suitable create/read/update/delete methods for your resources.
+#. It automatically provides suitable create/read/update/delete methods for your views.
 #. Input validation occurs automatically, by using appropriate `ModelForms <http://docs.djangoproject.com/en/dev/topics/forms/modelforms/>`_.
 
-We'll start of defining two resources in our urlconf again.
+Here's the model we're working from in this example:
-
-``urls.py``
-
-.. include:: ../../examples/modelresourceexample/urls.py
-    :literal:
-
-Here's the models we're working from in this example.  It's usually a good idea to make sure you provide the :func:`get_absolute_url()` `permalink <http://docs.djangoproject.com/en/dev/ref/models/instances/#get-absolute-url>`_ for all models you want to expose via the API.
 
 ``models.py``
 
 .. include:: ../../examples/modelresourceexample/models.py
     :literal:
 
+To add an API for the model, all we need to do is create a Resource for the model, and map a couple of views to it in our urlconf.
+
+``urls.py``
+
+.. include:: ../../examples/modelresourceexample/urls.py
+    :literal:
+
 And we're done.  We've now got a fully browseable API, which supports multiple input and output media types, and has all the nice automatic field validation that Django gives us for free.
 
 We can visit the API in our browser:
@@ -49,5 +49,3 @@ Or access it from the command line using curl:
     #  Demonstrates API's input validation using JSON input
     bash: curl -X POST -H 'Content-Type: application/json' --data-binary '{"foo":true}' http://api.django-rest-framework.org/model-resource-example/
    {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}}
-
-We could also have added the handler methods :meth:`.Resource.get()`, :meth:`.Resource.post()` etc... seen in the last example, but Django REST framework provides nice default implementations for us that do exactly what we'd expect them to. 

docs/examples/views.rst

@@ -1,7 +1,7 @@
-.. _resources:
+.. _views:
 
-Getting Started - Resources
+Getting Started - Views
----------------------------
+-----------------------
 
 .. note::
 
@@ -15,12 +15,12 @@ Getting Started - Resources
 
 We're going to start off with a simple example, that demonstrates a few things:
 
-#. Creating resources.
+#. Creating views.
-#. Linking resources.
+#. Linking views.
-#. Writing method handlers on resources.
+#. Writing method handlers on views.
-#. Adding form validation to resources.
+#. Adding form validation to views.
 
-First we'll define two resources in our urlconf.
+First we'll define two views in our urlconf.
 
 ``urls.py``
 
@@ -34,7 +34,7 @@ Now we'll add a form that we'll use for input validation.  This is completely op
 .. include:: ../../examples/resourceexample/forms.py
     :literal:
 
-Now we'll write our resources.  The first is a read only resource that links to three instances of the second.  The second resource just has some stub handler methods to help us see that our example is working.
+Now we'll write our views.  The first is a read only view that links to three instances of the second.  The second view just has some stub handler methods to help us see that our example is working.
 
 ``views.py``
 

docs/index.rst

@@ -89,17 +89,17 @@ Using Django REST framework can be as simple as adding a few lines to your urlco
 
 Django REST framework comes with two "getting started" examples.
 
-#. :ref:`resources`
+#. :ref:`views`
-#. :ref:`modelresources`
+#. :ref:`modelviews`
 	
 Examples
 --------
 
 There are a few real world web API examples included with Django REST framework.
 
-#. :ref:`objectstore` - Using :class:`.Resource` for resources that do not map to models.
+#. :ref:`objectstore` - Using :class:`views.View` classes for APIs that do not map to models.
-#. :ref:`codehighlighting` - Using :class:`.Resource` with forms for input validation.
+#. :ref:`codehighlighting` - Using :class:`views.View` classes with forms for input validation.
-#. :ref:`blogposts` - Using :class:`.ModelResource` for resources that map directly to models.
+#. :ref:`blogposts` - Using :class:`views.ModelView` classes for APIs that map directly to models.
 
 All the examples are freely available for testing in the sandbox:
 
@@ -143,8 +143,8 @@ Examples Reference
 .. toctree::
   :maxdepth: 1
   
-  examples/resources
+  examples/views
-  examples/modelresources
+  examples/modelviews
   examples/objectstore
   examples/pygments
   examples/blogpost

examples/resourceexample/urls.py

@@ -1,7 +1,7 @@
 from django.conf.urls.defaults import patterns, url
-from resourceexample.views import ExampleResource, AnotherExampleResource
+from resourceexample.views import ExampleView, AnotherExampleView
 
 urlpatterns = patterns('',
-    url(r'^$',                 ExampleResource.as_view(), name='example-resource'),
+    url(r'^$',                 ExampleView.as_view(), name='example'),
-    url(r'^(?P<num>[0-9]+)/$', AnotherExampleResource.as_view(), name='another-example-resource'),
+    url(r'^(?P<num>[0-9]+)/$', AnotherExampleView.as_view(), name='another-example'),
 )

examples/resourceexample/views.py

@@ -1,42 +1,45 @@
 from django.core.urlresolvers import reverse
 
 from djangorestframework.views import View
-from djangorestframework.resources import FormResource
 from djangorestframework.response import Response
 from djangorestframework import status
 
 from resourceexample.forms import MyForm
 
-class MyFormValidation(FormResource):
-    """
-    A resource which applies form validation on the input.
-    """
-    form = MyForm
 
-    
+class ExampleView(View):
-class ExampleResource(View):
     """
-    A basic read-only resource that points to 3 other resources.
+    A basic read-only view that points to 3 other views.
     """
 
     def get(self, request):
-        return {"Some other resources": [reverse('another-example-resource', kwargs={'num':num}) for num in range(3)]}
+        """
+        Handle GET requests, returning a list of URLs pointing to 3 other views.
+        """
+        return {"Some other resources": [reverse('another-example', kwargs={'num':num}) for num in range(3)]}
 
 
-class AnotherExampleResource(View):
+class AnotherExampleView(View):
     """
-    A basic GET-able/POST-able resource.
+    A basic view, that can be handle GET and POST requests.
+    Applies some simple form validation on POST requests.
     """
-    resource = MyFormValidation
+    form = MyForm
 
     def get(self, request, num):
-        """Handle GET requests"""
+        """
+        Handle GET requests.
+        Returns a simple string indicating which view the GET request was for.
+        """
         if int(num) > 2:
             return Response(status.HTTP_404_NOT_FOUND)
         return "GET request to AnotherExampleResource %s" % num
     
     def post(self, request, num):
-        """Handle POST requests"""
+        """
+        Handle POST requests, with form validation.
+        Returns a simple string indicating what content was supplied.
+        """
         if int(num) > 2:
             return Response(status.HTTP_404_NOT_FOUND)
         return "POST request to AnotherExampleResource %s, with content: %s" % (num, repr(self.CONTENT))