Clean up the docs

djangorestframework/authenticators.py

@@ -1,3 +1,9 @@
+"""The :mod:`authenticators` modules provides for pluggable authentication behaviour.
+
+Authentication behaviour is provided by adding the mixin class :class:`AuthenticatorMixin` to a :class:`.Resource` or Django :class:`View` class.
+
+The set of authenticators which are use is then specified by setting the :attr:`authenticators` attribute on the class, and listing a set of authenticator classes.
+"""
 from django.contrib.auth import authenticate
 from django.middleware.csrf import CsrfViewMiddleware
 from djangorestframework.utils import as_tuple
@@ -5,11 +11,14 @@ import base64
 
 
 class AuthenticatorMixin(object):
+    """Adds pluggable authentication behaviour."""
+    
+    """The set of authenticators to use."""
     authenticators = None
 
     def authenticate(self, request):
         """Attempt to authenticate the request, returning an authentication context or None.
-        An authentication context may be any object, although in many cases it will be a User instance."""
+        An authentication context may be any object, although in many cases it will simply be a :class:`User` instance."""
         
         # Attempt authentication against each authenticator in turn,
         # and return None if no authenticators succeed in authenticating the request.

djangorestframework/emitters.py

@@ -32,6 +32,12 @@ _MSIE_USER_AGENT = re.compile(r'^Mozilla/[0-9]+\.[0-9]+ \([^)]*; MSIE [0-9]+\.[0
 
 
 class EmitterMixin(object):
+    """Adds behaviour for pluggable Emitters to a :class:`.Resource` or Django :class:`View`. class.
+    
+    Default behaviour is to use standard HTTP Accept header content negotiation.
+    Also supports overidding the content type by specifying an _accept= parameter in the URL.
+    Ignores Accept headers from Internet Explorer user agents and uses a sensible browser Accept header instead."""
+
     ACCEPT_QUERY_PARAM = '_accept'        # Allow override of Accept header in URL query params
     REWRITE_IE_ACCEPT_HEADER = True
 
@@ -40,6 +46,7 @@ class EmitterMixin(object):
     emitters = ()
 
     def emit(self, response):
+        """Takes a :class:`Response` object and returns a Django :class:`HttpResponse`."""
         self.response = response
 
         try:

docs/examples/blogpost.rst

@@ -1,5 +1,7 @@
-ModelResource example - Blog posts
+.. _blogposts:
-==================================
+
+Blog Posts API
+==============
 
 * http://api.django-rest-framework.org/blog-post/
 

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. 

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/
 

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
 -----------------

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."]}}

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:

docs/howto/mixin.rst

@@ -0,0 +1,30 @@
+Using Django REST framework Mixin classes
+=========================================
+
+This example demonstrates creating a REST API **without** using Django REST framework's :class:`.Resource` or :class:`.ModelResource`,
+but instead using Django :class:`View` class, and adding the :class:`EmitterMixin` class to provide full HTTP Accept header content negotiation,
+a browseable Web API, and much of the other goodness that Django REST framework gives you for free.
+
+.. note::
+
+    A live sandbox instance of this API is available for testing:
+    
+    * http://api.django-rest-framework.org/mixin/
+
+    You can browse the API using a web browser, or from the command line::
+
+        curl -X GET http://api.django-rest-framework.org/mixin/
+
+
+URL configuration
+-----------------
+
+Everything we need for this example can go straight into the URL conf...
+
+``urls.py``
+
+.. include:: ../../examples/mixin/urls.py
+    :literal:
+
+That's it.  Auto-magically our API now supports multiple output formats, specified either by using standard HTTP Accept header content negotiation, or by using the `&_accept=application/json` style parameter overrides.
+We even get a nice HTML view which can be used to self-document our API.

docs/howto/setup.rst

@@ -0,0 +1,28 @@
+.. _setup:
+
+Setup
+=====
+
+Template Loaders
+----------------
+
+Django REST framework uses a few templates for the HTML and plain text documenting emitters.
+
+* Ensure ``TEMPLATE_LOADERS`` setting contains ``'django.template.loaders.app_directories.Loader'``.
+
+This will be the case by default so you shouldn't normally need to do anything here.
+
+Admin Styling
+-------------
+
+Django REST framework uses the admin media for styling.  When running using Django's testserver this is automatically served for you, but once you move onto a production server, you'll want to make sure you serve the admin media seperatly, exactly as you would do if using the Django admin.
+
+* Ensure that the ``ADMIN_MEDIA_PREFIX`` is set appropriately and that you are serving the admin media.  (Django's testserver will automatically serve the admin media for you)
+
+Markdown
+--------
+
+The Python `markdown library <http://www.freewisdom.org/projects/python-markdown/>`_ is not required but comes recommended.
+
+If markdown is installed your :class:`.Resource` descriptions can include `markdown style formatting <http://daringfireball.net/projects/markdown/syntax>`_ which will be rendered by the HTML documenting emitter.
+

docs/howto/usingcurl.rst

@@ -17,11 +17,7 @@ There are a few things that can be helpful to remember when using CURL with djan
 
     curl -X GET -H 'Accept: text/plain' http://example.com/my-api/
 
-#. All POST requests should include an ```X-Requested-With: XMLHttpRequest`` header <http://docs.djangoproject.com/en/dev/ref/contrib/csrf/#how-it-works>`_::
+#. ``POST`` and ``PUT`` requests can contain form data (ie ``Content-Type: application/x-www-form-urlencoded``)::
-
-    curl -X POST -H 'X-Requested-With: XMLHttpRequest' --data 'foo=bar' http://example.com/my-api/
-
-#. ``POST`` and ``PUT`` requests can contain form data (ie ``Content-Type:: application/x-www-form-urlencoded``)::
 
     curl -X PUT --data 'foo=bar' http://example.com/my-api/some-resource/
 

docs/index.rst

@@ -9,29 +9,28 @@ Django REST framework
 Introduction
 ------------
 
-Django REST framework is a lightweight REST framework for Django.
+Django REST framework aims to make it easy to build well-connected, self-describing Web APIs with a minimum of fuss.
-
-It aims to make it easy to build well-connected, self-describing Web APIs with a minimum of fuss.
 
 Features:
 
-* Clean, simple, class-based views for Resources.
+* Automatically provides a Django Admin style `browse-able self-documenting API <http://api.django-rest-framework.org>`_.
-* Support for ModelResources with nice default implementations and input validation.
+* Clean, simple, views for Resources, using Django's new `class based views <http://docs.djangoproject.com/en/dev/topics/class-based-views/>`_.
-* Automatically provides a browse-able self-documenting API.
+* Support for ModelResources with out-of-the-box default implementations and input validation.
-* Pluggable Emitters, Parsers and Authenticators - Easy to customise.
+* Pluggable :mod:`.emitters`, :mod:`parsers`, :mod:`validators` and :mod:`authenticators` - Easy to customise.
-* Content type negotiation using Accept headers.
+* Content type negotiation using HTTP Accept headers.
 * Optional support for forms as input validation.
-* Modular architecture - Easy to extend and modify.
+* Modular architecture - The MixIn classes can even be used without using the core :class:`.Resource` or :class:`.ModelResource` classes.
+
+For more information please head on over to the `discussion group <http://groups.google.com/group/django-rest-framework>`_.
+
+Bug reports and feature suggestions are greatful received on the `issue tracker <https://bitbucket.org/tomchristie/django-rest-framework/issues?sort=version>`_.
 
 Requirements
 ------------
 
-* Python 2.6
+* Python (2.5, 2.6, 2.7 supported)
-* Django 1.2
+* Django (1.2, 1.3 supported)
 
-.. note::
-
-    Support for a wider range of Python & Django versions is planned, but right now django-rest-framework is only tested against these versions.
 
 Installation & Setup
 --------------------
@@ -43,148 +42,88 @@ To get a local copy of the repository use mercurial::
 
 To add django-rest-framework to a django project:
 
-* Copy or symlink the ``djangorestframework`` directory into python's ``site-packages`` directory, or otherwise ensure that the ``djangorestframework`` directory is on your ``PYTHONPATH``.
+* Ensure that the ``djangorestframework`` directory is on your ``PYTHONPATH``.
 * Add ``djangorestframework`` to your ``INSTALLED_APPS``.
-* Ensure the ``TEMPLATE_LOADERS`` setting contains the item ``'django.template.loaders.app_directories.Loader'``. (It will do by default, so you shouldn't normally need to do anything here.)
 
-Getting Started - Resources
+That's normally all you'll need to do to get Django REST framework set up on a standard installation using the testserver.
----------------------------
 
-We're going to start off with a simple example, that demonstrates
+For more information take a look at the :ref:`setup` section.
-a few things:
 
-#. Creating resources.
+Getting Started
-#. Linking resources.
+---------------
-#. Writing method handlers on resources.
-#. Adding form validation to resources.
 
-First we'll define two resources in our urlconf.
+Using Django REST framework can be as simple as adding a few lines to your urlconf::
 
-``urls.py``
+    from django.conf.urls.defaults import patterns, url
+    from djangorestframework import ModelResource, RootModelResource
+    from models import MyModel
 
-.. include:: ../examples/resourceexample/urls.py
+    urlpatterns = patterns('',
-    :literal:
+        url(r'^$', RootModelResource.as_view(model=MyModel)),
+        url(r'^(?P<pk>[^/]+)/$', ModelResource.as_view(model=MyModel)),
+     )
 
-Now we'll add a form that we'll use for input validation.  This is completely optional, but it's often useful.
+Django REST framework comes with two "getting started" examples.
-
-``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 -H 'X-Requested-With: XMLHttpRequest' --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 'X-Requested-With: XMLHttpRequest' -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."]}}
-
-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 -H 'X-Requested-With: XMLHttpRequest' --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 'X-Requested-With: XMLHttpRequest' -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. 
 
+#. :ref:`resources`
+#. :ref:`modelresources`
+	
 Examples
 --------
 
-There's a few real world examples included with django-rest-framework.
+There are a few real world web API examples included with Django REST framework.
-These demonstrate the following use cases:
 
-#. Using :class:`.Resource` for resources that do not map to models.
+#. :ref:`objectstore` - Using :class:`.Resource` for resources that do not map to models.
-#. Using :class:`.Resource` with forms for input validation.
+#. :ref:`codehighlighting` - Using :class:`.Resource` with forms for input validation.
-#. Using :class:`.ModelResource` for resources that map directly to models.
+#. :ref:`blogposts` - Using :class:`.ModelResource` for resources that map directly to models.
 
-All the examples are freely available for testing in the sandbox here: http://api.django-rest-framework.org
+All the examples are freely available for testing in the sandbox:
+
+* http://api.django-rest-framework.org
+
+(The :ref:`sandbox` resource is also documented.)
 
-.. toctree::
-  :maxdepth: 1
 
-  examples/objectstore
-  examples/pygments
-  examples/blogpost
 
 How Tos, FAQs & Notes
 ---------------------
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
+  howto/setup
   howto/usingcurl
   howto/alternativeframeworks
+  howto/mixin
 
 Library Reference
 -----------------
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
   library/resource
   library/modelresource
   library/emitters
   library/parsers
   library/authenticators
+  library/validators
   library/response
+  library/status
 
+Examples Reference
+------------------
+
+.. toctree::
+  :maxdepth: 1
+  
+  examples/resources
+  examples/modelresources
+  examples/objectstore
+  examples/pygments
+  examples/blogpost
+  examples/sandbox
+  howto/mixin
 
 Indices and tables
 ------------------

docs/library/authenticators.rst

@@ -1,30 +1,5 @@
 :mod:`authenticators`
 =====================
 
-.. module:: authenticators
+.. automodule:: authenticators
-
+   :members:
-The authenticators module provides a standard set of authentication methods that can be plugged in to a :class:`.Resource`, as well as providing a template by which to write custom authentication methods.
-
-The base class
---------------
-
-All authenticators must subclass the :class:`BaseAuthenticator` class and override it's :func:`authenticate` method.
-
-.. class:: BaseAuthenticator
-
-   .. method:: authenticate(request)
-
-      Authenticate the request and return the authentication context or None.
-
-      The default permission checking on :class:`.Resource` will use the allowed_methods attribute for permissions if the authentication context is not None, and use anon_allowed_methods otherwise.
-
-      The authentication context is passed to the handler calls (eg :meth:`.Resource.get`, :meth:`.Resource.post` etc...) in order to allow them to apply any more fine grained permission checking at the point the response is being generated.
-
-      This function must be overridden to be implemented.
-
-Provided authenticators
------------------------
-
-.. note::
-
-    TODO - document this module properly

docs/library/resource.rst

@@ -3,7 +3,7 @@
 
 .. module:: resource
 
-The :mod:`resource` module is the core of FlyWheel.  It provides the :class:`Resource` base class which handles incoming HTTP requests and maps them to method calls, performing authentication, input deserialization, input validation and output serialization.
+The :mod:`resource` module is the core of Django REST framework.  It provides the :class:`Resource` base class which handles incoming HTTP requests and maps them to method calls, performing authentication, input deserialization, input validation and output serialization.
 
 Resources are created by sublassing :class:`Resource`, setting a number of class attributes, and overriding one or more methods.
 

docs/library/status.rst

@@ -0,0 +1,5 @@
+:mod:`status`
+===============
+
+.. automodule:: status
+   :members:

docs/library/validators.rst

@@ -0,0 +1,5 @@
+:mod:`validators`
+===============
+
+.. automodule:: validators
+   :members: