Clean up the docs

6 files changed, 125 insertions, 9 deletions

diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst
index aeb3d2fd..07f7cbc5 100644
--- a/docs/examples/blogpost.rst
+++ b/docs/examples/blogpost.rst
@@ -1,5 +1,7 @@
-ModelResource example - Blog posts
-==================================
+.. _blogposts:
+
+Blog Posts API
+==============
 
 * http://api.django-rest-framework.org/blog-post/
 
diff --git a/docs/examples/modelresources.rst b/docs/examples/modelresources.rst
new file mode 100644
index 00000000..ec0fa36c
--- /dev/null
+++ b/docs/examples/modelresources.rst
@@ -0,0 +1,50 @@
+.. _modelresources:
+
+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.
+#. 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.
+
+``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:
+
+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.
+
+``views.py``
+
+.. include:: ../../examples/modelresourceexample/views.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:
+
+* http://api.django-rest-framework.org/model-resource-example/
+
+Or access it from the command line using curl:
+
+.. code-block:: bash
+
+    #  Demonstrates API's input validation using form input
+    bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/model-resource-example/
+    {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}}
+
+    #  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/objectstore.rst b/docs/examples/objectstore.rst
index 7865242d..38bdbc98 100644
--- a/docs/examples/objectstore.rst
+++ b/docs/examples/objectstore.rst
@@ -1,5 +1,7 @@
-Resource example - An object store
-==================================
+.. _objectstore:
+
+Object Store API
+================
 
 * http://api.django-rest-framework.org/object-store/
 
diff --git a/docs/examples/pygments.rst b/docs/examples/pygments.rst
index 6ba2805f..decc2f65 100644
--- a/docs/examples/pygments.rst
+++ b/docs/examples/pygments.rst
@@ -1,5 +1,7 @@
-Resource with form validation - A pygments pastebin
-===================================================
+.. _codehighlighting:
+
+Code Highlighting API
+=====================
 
 This example demonstrates creating a REST API using a :class:`.Resource` with some form validation on the input.
 We're going to provide a simple wrapper around the awesome `pygments <http://pygments.org/>`_ library, to create the Web API for a simple pastebin.
@@ -8,12 +10,10 @@ We're going to provide a simple wrapper around the awesome `pygments <http://pyg
 
     A live sandbox instance of this API is available at http://api.django-rest-framework.org/pygments/
 
-    You can browse the API using a web browser(1), or from the command line(2)::
+    You can browse the API using a web browser, or from the command line::
 
         curl -X GET http://api.django-rest-framework.org/pygments/ -H 'Accept: text/plain'
 
-    #. Except for Internet Explorer.  Because it's `dumb <http://www.gethifi.com/blog/browser-rest-http-accept-headers>`_.
-    #. See `using CURL with django-rest-framework <http://django-rest-framework.org/howto/usingcurl.html>`_ for more details.
 
 URL configuration
 -----------------
diff --git a/docs/examples/resources.rst b/docs/examples/resources.rst
new file mode 100644
index 00000000..0b76c466
--- /dev/null
+++ b/docs/examples/resources.rst
@@ -0,0 +1,48 @@
+.. _resources:
+
+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.
+
+First we'll define two resources in our urlconf.
+
+``urls.py``
+
+.. include:: ../../examples/resourceexample/urls.py
+    :literal:
+
+Now we'll add a form that we'll use for input validation.  This is completely optional, but it's often useful.
+
+``forms.py``
+
+.. 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.
+
+``views.py``
+
+.. include:: ../../examples/resourceexample/views.py
+    :literal:
+
+That's us done.  Our API now provides both programmatic access using JSON and XML, as well a nice browseable HTML view, so we can now access it both from the browser:
+
+* http://api.django-rest-framework.org/resource-example/
+
+And from the command line:
+
+.. code-block:: bash
+
+    # Demonstrates API's input validation using form input
+    bash: curl -X POST --data 'foo=true' http://api.django-rest-framework.org/resource-example/1/
+    {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}}
+
+    #  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/resource-example/1/
+   {"detail": {"bar": ["This field is required."], "baz": ["This field is required."]}}
diff --git a/docs/examples/sandbox.rst b/docs/examples/sandbox.rst
new file mode 100644
index 00000000..b6658ad9
--- /dev/null
+++ b/docs/examples/sandbox.rst
@@ -0,0 +1,14 @@
+.. _sandbox:
+
+Sandbox Root API
+================
+
+The Resource
+------------
+
+The root level resource of the Django REST framework examples is a simple read only resource:
+
+``view.py``
+
+.. include:: ../../examples/sandbox/views.py
+    :literal: