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
------------------
-
-``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.
+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.
 
-#``views.py``
+``urls.py``
 
-#.. include:: ../../examples/blogpost/views.py
-#   :literal:
+.. include:: ../../examples/blogpost/urls.py
+    :literal:
\ No newline at end of file

docs/examples/modelresources.rst → docs/examples/modelviews.rst

-.. _modelresources:
+.. _modelviews:
 
-Getting Started - Model Resources
----------------------------------
+Getting Started - Model Views
+-----------------------------
 
 .. note::
 
@@ -15,21 +15,21 @@ 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``
+``models.py``
 
-.. include:: ../../examples/modelresourceexample/urls.py
+.. include:: ../../examples/modelresourceexample/models.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.
+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.
 
-``models.py``
+``urls.py``
 
-.. include:: ../../examples/modelresourceexample/models.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.
@@ -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/resources.rst → docs/examples/views.rst

-.. _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.
-#. Linking resources.
-#. Writing method handlers on resources.
-#. Adding form validation to resources.
+#. Creating views.
+#. Linking views.
+#. Writing method handlers on views.
+#. 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:`modelresources`
+#. :ref:`views`
+#. :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:`codehighlighting` - Using :class:`.Resource` with forms for input validation.
-#. :ref:`blogposts` - Using :class:`.ModelResource` for resources that map directly to models.
+#. :ref:`objectstore` - Using :class:`views.View` classes for APIs that do not map to models.
+#. :ref:`codehighlighting` - Using :class:`views.View` classes with forms for input validation.
+#. :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/modelresources
+  examples/views
+  examples/modelviews
   examples/objectstore
   examples/pygments
   examples/blogpost

examples/resourceexample/urls.py

 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'^(?P<num>[0-9]+)/$', AnotherExampleResource.as_view(), name='another-example-resource'),
+    url(r'^$',                 ExampleView.as_view(), name='example'),
+    url(r'^(?P<num>[0-9]+)/$', AnotherExampleView.as_view(), name='another-example'),
 )

examples/resourceexample/views.py

 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 ExampleResource(View):
+class ExampleView(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))