8 files changed, 117 insertions, 81 deletions
diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst
index 9d762f52..be91913d 100644
--- a/docs/examples/blogpost.rst
+++ b/docs/examples/blogpost.rst
@@ -8,26 +8,32 @@ 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
+----------------------
+
+We need to create two resources that we map to our two existing models, in order to describe how the models should be serialized.
+Our resource descriptions will typically go into a module called something like 'resources.py'
 
-``urls.py``
+``resources.py``
 
-.. include:: ../../examples/blogpost/urls.py
+.. include:: ../../examples/blogpost/resources.py
     :literal:
 
-Creating the resources
-----------------------
+Creating views for our 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've created the resources there's very little we need to do to create the API.
+For each resource we'll create a base view, and an instance view.
+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:
-\ No newline at end of file
+.. include:: ../../examples/blogpost/urls.py
+    :literal:
diff --git a/docs/examples/modelresources.rst b/docs/examples/modelviews.rst
index 676656a7..c60c9f24 100644
--- a/docs/examples/modelresources.rst
+++ b/docs/examples/modelviews.rst
@@ -1,7 +1,7 @@
-.. _modelresources:
+.. _modelviews:
 
-Getting Started - Model Resources
----------------------------------
+Getting Started - Model Views
+-----------------------------
 
 .. note::
 
@@ -15,28 +15,28 @@ 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, first we need to create a Resource for the model.
 
-``models.py``
+``resources.py``
 
-.. include:: ../../examples/modelresourceexample/models.py
+.. include:: ../../examples/modelresourceexample/resources.py
     :literal:
 
-Now that we've got some models and a urlconf, there's very little code to write.  We'll create a :class:`.ModelResource` to map to instances of our models, and a top level :class:`.RootModelResource` to list the existing instances and to create new instances.
+Then we simply map a couple of views to the Resource in our urlconf.
 
-``views.py``
+``urls.py``
 
-.. include:: ../../examples/modelresourceexample/views.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.
@@ -56,5 +56,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. 
diff --git a/docs/examples/resources.rst b/docs/examples/views.rst
index f3242421..59e13976 100644
--- a/docs/examples/resources.rst
+++ b/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.
-#. 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``
 
diff --git a/docs/howto/alternativeframeworks.rst b/docs/howto/alternativeframeworks.rst
index c6eba1dd..dc8d1ea6 100644
--- a/docs/howto/alternativeframeworks.rst
+++ b/docs/howto/alternativeframeworks.rst
@@ -1,6 +1,35 @@
-Alternative Frameworks
-======================
+Alternative frameworks & Why Django REST framework
+==================================================
 
-#. `django-piston <https://bitbucket.org/jespern/django-piston/wiki/Home>`_ is excellent, and has a great community behind it.  This project is based on piston code in parts.
+Alternative frameworks
+----------------------
 
-#. `django-tasypie <https://github.com/toastdriven/django-tastypie>`_ is also well worth looking at.
+There are a number of alternative REST frameworks for Django:
+
+* `django-piston <https://bitbucket.org/jespern/django-piston/wiki/Home>`_ is very mature, and has a large community behind it.  This project was originally based on piston code in parts.
+* `django-tasypie <https://github.com/toastdriven/django-tastypie>`_ is also very good, and has a very active and helpful developer community and maintainers.
+* Other interesting projects include `dagny <https://github.com/zacharyvoase/dagny>`_ and `dj-webmachine <http://benoitc.github.com/dj-webmachine/>`_
+
+
+Why use Django REST framework?
+------------------------------
+
+The big benefits of using Django REST framework come down to:
+
+1. It's based on Django's class based views, which makes it simple, modular, and future-proof.
+2. It stays as close as possible to Django idioms and language throughout.
+3. The browse-able API makes working with the APIs extremely quick and easy.
+
+
+Why was this project created?
+-----------------------------
+
+For me the browse-able API is the most important aspect of Django REST framework.
+
+I wanted to show that Web APIs could easily be made Web browse-able,
+and demonstrate how much better browse-able Web APIs are to work with.
+
+Being able to navigate and use a Web API directly in the browser is a huge win over only having command line and programmatic
+access to the API.  It enables the API to be properly self-describing, and it makes it much much quicker and easier to work with.
+There's no fundamental reason why the Web APIs we're creating shouldn't be able to render to HTML as well as JSON/XML/whatever,
+and I really think that more Web API frameworks *in whatever language* ought to be taking a similar approach.
diff --git a/docs/howto/setup.rst b/docs/howto/setup.rst
index e59ea90e..b4fbc037 100644
--- a/docs/howto/setup.rst
+++ b/docs/howto/setup.rst
@@ -3,6 +3,13 @@
 Setup
 =====
 
+Installing into site-packages
+-----------------------------
+
+If you need to manually install Django REST framework to your ``site-packages`` directory, run the ``setup.py`` script::
+
+    python setup.py install
+
 Template Loaders
 ----------------
 
diff --git a/docs/howto/usingcurl.rst b/docs/howto/usingcurl.rst
index e7edfef9..2ad2c764 100644
--- a/docs/howto/usingcurl.rst
+++ b/docs/howto/usingcurl.rst
@@ -23,4 +23,8 @@ There are a few things that can be helpful to remember when using CURL with djan
 
 #. Or any other content type::
 
-    curl -X PUT -H 'Content-Type: application/json' --data-binary '{"foo":"bar"}' http://example.com/my-api/some-resource/
-\ No newline at end of file
+    curl -X PUT -H 'Content-Type: application/json' --data-binary '{"foo":"bar"}' http://example.com/my-api/some-resource/
+
+#. You can use basic authentication to send the username and password::
+
+    curl -X GET -H 'Accept: application/json' -u <user>:<password> http://example.com/my-api/
+\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 3b4e9c49..8a285271 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,15 +30,11 @@ Resources
 
 * The ``djangorestframework`` package is `available on PyPI <http://pypi.python.org/pypi/djangorestframework>`_.
 * We have an active `discussion group <http://groups.google.com/group/django-rest-framework>`_ and a `project blog <http://blog.django-rest-framework.org>`_. 
-* Bug reports are handled on the `issue tracker <https://bitbucket.org/tomchristie/django-rest-framework/issues?sort=version>`_.
-* There is a `Jenkins CI server <http://datacenter.tibold.nl/job/djangorestframework/>`_ which tracks test status and coverage reporting.  (Thanks Marko!)
-* Get with in touch with `@thisneonsoul <https://twitter.com/thisneonsoul>`_ on twitter.
+* Bug reports are handled on the `issue tracker <https://github.com/tomchristie/django-rest-framework/issues>`_.
+* There is a `Jenkins CI server <http://jenkins.tibold.nl/job/djangorestframework/>`_ which tracks test status and coverage reporting.  (Thanks Marko!)
 
 Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*.
 
-We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking!  (See: `Forking a Bitbucket Repository 
-<http://confluence.atlassian.com/display/BITBUCKET/Forking+a+Bitbucket+Repository>`_, or `Fork A GitHub Repo <http://help.github.com/fork-a-repo/>`_)
-
 Requirements
 ------------
 
@@ -46,8 +42,8 @@ Requirements
 * Django (1.2, 1.3 supported)
 
 
-Installation & Setup
---------------------
+Installation
+------------
 
 
 You can install Django REST framework using ``pip`` or ``easy_install``::
@@ -59,61 +55,51 @@ Or get the latest development version using mercurial or git::
     hg clone https://bitbucket.org/tomchristie/django-rest-framework
     git clone git@github.com:tomchristie/django-rest-framework.git
 
-Or you can download the current release:
-
-* `django-rest-framework-0.1.tar.gz <https://bitbucket.org/tomchristie/django-rest-framework/downloads/django-rest-framework-0.1.tar.gz>`_
-* `django-rest-framework-0.1.zip <https://bitbucket.org/tomchristie/django-rest-framework/downloads/django-rest-framework-0.1.zip>`_
-
-and then install Django REST framework to your ``site-packages`` directory, by running the ``setup.py`` script::
+Or you can `download the current release <http://pypi.python.org/pypi/djangorestframework>`_.
 
-    python setup.py install
+Setup
+-----
 
-**To add django-rest-framework to a Django project:**
+To add Django REST framework to a Django project:
 
 * Ensure that the ``djangorestframework`` directory is on your ``PYTHONPATH``.
 * Add ``djangorestframework`` to your ``INSTALLED_APPS``.
 
-For more information take a look at the :ref:`setup` section.
+For more information on settings take a look at the :ref:`setup` section.
 
 Getting Started
 ---------------
 
-Using Django REST framework can be as simple as adding a few lines to your urlconf and adding a `permalink <http://docs.djangoproject.com/en/dev/ref/models/instances/#get-absolute-url>`_ to your model.
+Using Django REST framework can be as simple as adding a few lines to your urlconf.
 
-`urls.py`::
+``urls.py``::
 
     from django.conf.urls.defaults import patterns, url
-    from djangorestframework import ModelResource, RootModelResource
-    from models import MyModel
+    from djangorestframework.resources import ModelResource
+    from djangorestframework.views import ListOrCreateModelView, InstanceModelView
+    from myapp.models import MyModel
+    
+    class MyResource(ModelResource):
+        model = MyModel
 
     urlpatterns = patterns('',
-        url(r'^$', RootModelResource.as_view(model=MyModel)),
-        url(r'^(?P<pk>[^/]+)/$', ModelResource.as_view(model=MyModel), name='my-model'),
-     )
-
-`models.py`::
-
-    class MyModel(models.Model):
-
-        # (Rest of model definition...)
-
-        @models.permalink
-        def get_absolute_url(self):
-            return ('my-model', (self.pk,))
+        url(r'^$', ListOrCreateModelView.as_view(resource=MyResource)),
+        url(r'^(?P<pk>[^/]+)/$', InstanceModelView.as_view(resource=MyResource)),
+    )
 
 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:
 
@@ -148,6 +134,7 @@ Library Reference
   library/renderers
   library/resource
   library/response
+  library/serializer
   library/status
   library/views
 
@@ -157,8 +144,8 @@ Examples Reference
 .. toctree::
   :maxdepth: 1
   
-  examples/resources
-  examples/modelresources
+  examples/views
+  examples/modelviews
   examples/objectstore
   examples/pygments
   examples/blogpost
diff --git a/docs/library/serializer.rst b/docs/library/serializer.rst
new file mode 100644
index 00000000..63dd3308
--- /dev/null
+++ b/docs/library/serializer.rst
@@ -0,0 +1,5 @@
+:mod:`serializer` 
+=================
+
+.. automodule:: serializer
+   :members: