Added buildout stuff and made changes accordingly

--HG--
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt
rename : taskapp/models.py => parts/django/django/conf/app_template/models.py
rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py
rename : taskapp/views.py => parts/django/django/conf/app_template/views.py
rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py
rename : profile/forms.py => pytask/profile/forms.py
rename : profile/management/__init__.py => pytask/profile/management/__init__.py
rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py
rename : profile/models.py => pytask/profile/models.py
rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py
rename : taskapp/tests.py => pytask/profile/tests.py
rename : profile/urls.py => pytask/profile/urls.py
rename : profile/utils.py => pytask/profile/utils.py
rename : profile/views.py => pytask/profile/views.py
rename : static/css/base.css => pytask/static/css/base.css
rename : taskapp/tests.py => pytask/taskapp/tests.py
rename : taskapp/views.py => pytask/taskapp/views.py
rename : templates/base.html => pytask/templates/base.html
rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html
rename : templates/profile/edit.html => pytask/templates/profile/edit.html
rename : templates/profile/view.html => pytask/templates/profile/view.html
rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html
rename : templates/registration/activate.html => pytask/templates/registration/activate.html
rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt
rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt
rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html
rename : templates/registration/login.html => pytask/templates/registration/login.html
rename : templates/registration/logout.html => pytask/templates/registration/logout.html
rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html
rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html
rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html
rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html
rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html
rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html
rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html
rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html
rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html
rename : utils.py => pytask/utils.py

88 files changed, 32532 insertions, 0 deletions

diff --git a/parts/django/docs/ref/authbackends.txt b/parts/django/docs/ref/authbackends.txt
new file mode 100644
index 0000000..a50b414
--- /dev/null
+++ b/parts/django/docs/ref/authbackends.txt
@@ -0,0 +1,35 @@
+=======================
+Authentication backends
+=======================
+
+.. module:: django.contrib.auth.backends
+   :synopsis: Django's built-in authentication backend classes.
+
+This document details the authentication backends that come with Django. For
+information on how to use them and how to write your own authentication
+backends, see the :ref:`Other authentication sources section
+<authentication-backends>` of the :doc:`User authentication guide
+</topics/auth>`.
+
+
+Available authentication backends
+=================================
+
+The following backends are available in :mod:`django.contrib.auth.backends`:
+
+.. class:: ModelBackend
+
+    This is the default authentication backend used by Django.  It
+    authenticates using usernames and passwords stored in the
+    :class:`~django.contrib.auth.models.User` model.
+
+
+.. class:: RemoteUserBackend
+
+    .. versionadded:: 1.1
+
+    Use this backend to take advantage of external-to-Django-handled
+    authentication.  It authenticates using usernames passed in
+    :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`.  See
+    the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
+    documentation.
diff --git a/parts/django/docs/ref/contrib/admin/_images/article_actions.png b/parts/django/docs/ref/contrib/admin/_images/article_actions.png
new file mode 100644
index 0000000..78a78ae
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/_images/article_actions.png
diff --git a/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png b/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png
new file mode 100644
index 0000000..6ea9439
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png
diff --git a/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png b/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png
new file mode 100644
index 0000000..391a629
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png
diff --git a/parts/django/docs/ref/contrib/admin/_images/user_actions.png b/parts/django/docs/ref/contrib/admin/_images/user_actions.png
new file mode 100644
index 0000000..fdbe2ad
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/_images/user_actions.png
diff --git a/parts/django/docs/ref/contrib/admin/_images/users_changelist.png b/parts/django/docs/ref/contrib/admin/_images/users_changelist.png
new file mode 100644
index 0000000..d5f9c01
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/_images/users_changelist.png
diff --git a/parts/django/docs/ref/contrib/admin/actions.txt b/parts/django/docs/ref/contrib/admin/actions.txt
new file mode 100644
index 0000000..0fab59e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/actions.txt
@@ -0,0 +1,351 @@
+=============
+Admin actions
+=============
+
+.. versionadded:: 1.1
+
+.. currentmodule:: django.contrib.admin
+
+The basic workflow of Django's admin is, in a nutshell, "select an object,
+then change it." This works well for a majority of use cases. However, if you
+need to make the same change to many objects at once, this workflow can be
+quite tedious.
+
+In these cases, Django's admin lets you write and register "actions" -- simple
+functions that get called with a list of objects selected on the change list
+page.
+
+If you look at any change list in the admin, you'll see this feature in
+action; Django ships with a "delete selected objects" action available to all
+models. For example, here's the user module from Django's built-in
+:mod:`django.contrib.auth` app:
+
+.. image:: _images/user_actions.png
+
+.. warning::
+
+    The "delete selected objects" action uses :meth:`QuerySet.delete()
+    <django.db.models.QuerySet.delete>` for efficiency reasons, which has an
+    important caveat: your model's ``delete()`` method will not be called.
+    
+    If you wish to override this behavior, simply write a custom action which
+    accomplishes deletion in your preferred manner -- for example, by calling
+    ``Model.delete()`` for each of the selected items.
+    
+    For more background on bulk deletion, see the documentation on :ref:`object
+    deletion <topics-db-queries-delete>`.
+
+Read on to find out how to add your own actions to this list.
+
+Writing actions
+===============
+
+The easiest way to explain actions is by example, so let's dive in.
+
+A common use case for admin actions is the bulk updating of a model. Imagine a
+simple news application with an ``Article`` model::
+
+    from django.db import models
+
+    STATUS_CHOICES = (
+        ('d', 'Draft'),
+        ('p', 'Published'),
+        ('w', 'Withdrawn'),
+    )
+
+    class Article(models.Model):
+        title = models.CharField(max_length=100)
+        body = models.TextField()
+        status = models.CharField(max_length=1, choices=STATUS_CHOICES)
+    
+        def __unicode__(self):
+            return self.title
+        
+A common task we might perform with a model like this is to update an
+article's status from "draft" to "published". We could easily do this in the
+admin one article at a time, but if we wanted to bulk-publish a group of
+articles, it'd be tedious. So, let's write an action that lets us change an
+article's status to "published."
+
+Writing action functions
+------------------------
+
+First, we'll need to write a function that gets called when the action is
+trigged from the admin. Action functions are just regular functions that take
+three arguments: 
+    
+    * The current :class:`ModelAdmin`
+    * An :class:`~django.http.HttpRequest` representing the current request,
+    * A :class:`~django.db.models.QuerySet` containing the set of objects
+      selected by the user.
+
+Our publish-these-articles function won't need the :class:`ModelAdmin` or the
+request object, but we will use the queryset::
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+        
+.. note::
+
+    For the best performance, we're using the queryset's :ref:`update method
+    <topics-db-queries-update>`. Other types of actions might need to deal
+    with each object individually; in these cases we'd just iterate over the
+    queryset::
+    
+        for obj in queryset:
+            do_something_with(obj)
+            
+That's actually all there is to writing an action! However, we'll take one
+more optional-but-useful step and give the action a "nice" title in the admin.
+By default, this action would appear in the action list as "Make published" --
+the function name, with underscores replaced by spaces. That's fine, but we
+can provide a better, more human-friendly name by giving the
+``make_published`` function a ``short_description`` attribute::
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+    make_published.short_description = "Mark selected stories as published"
+    
+.. note::
+
+    This might look familiar; the admin's ``list_display`` option uses the
+    same technique to provide human-readable descriptions for callback
+    functions registered there, too.
+    
+Adding actions to the :class:`ModelAdmin`
+-----------------------------------------
+
+Next, we'll need to inform our :class:`ModelAdmin` of the action. This works
+just like any other configuration option. So, the complete ``admin.py`` with
+the action and its registration would look like::
+
+    from django.contrib import admin
+    from myapp.models import Article
+
+    def make_published(modeladmin, request, queryset):
+        queryset.update(status='p')
+    make_published.short_description = "Mark selected stories as published"
+
+    class ArticleAdmin(admin.ModelAdmin):
+        list_display = ['title', 'status']
+        ordering = ['title']
+        actions = [make_published]
+
+    admin.site.register(Article, ArticleAdmin)
+    
+That code will give us an admin change list that looks something like this:
+
+.. image:: _images/article_actions.png
+    
+That's really all there is to it! If you're itching to write your own actions,
+you now know enough to get started. The rest of this document just covers more
+advanced techniques.
+
+Advanced action techniques
+==========================
+
+There's a couple of extra options and possibilities you can exploit for more
+advanced options.
+
+Actions as :class:`ModelAdmin` methods
+--------------------------------------
+
+The example above shows the ``make_published`` action defined as a simple
+function. That's perfectly fine, but it's not perfect from a code design point
+of view: since the action is tightly coupled to the ``Article`` object, it
+makes sense to hook the action to the ``ArticleAdmin`` object itself.
+
+That's easy enough to do::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        ...
+        
+        actions = ['make_published']
+
+        def make_published(self, request, queryset):
+            queryset.update(status='p')
+        make_published.short_description = "Mark selected stories as published"
+        
+Notice first that we've moved ``make_published`` into a method and renamed the
+`modeladmin` parameter to `self`, and second that we've now put the string
+``'make_published'`` in ``actions`` instead of a direct function reference. This
+tells the :class:`ModelAdmin` to look up the action as a method.
+
+Defining actions as methods gives the action more straightforward, idiomatic
+access to the :class:`ModelAdmin` itself, allowing the action to call any of the
+methods provided by the admin.
+
+.. _custom-admin-action:
+
+For example, we can use ``self`` to flash a message to the user informing her
+that the action was successful::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        ...
+
+        def make_published(self, request, queryset):
+            rows_updated = queryset.update(status='p')
+            if rows_updated == 1:
+                message_bit = "1 story was"
+            else:
+                message_bit = "%s stories were" % rows_updated
+            self.message_user(request, "%s successfully marked as published." % message_bit)
+
+This make the action match what the admin itself does after successfully
+performing an action:
+
+.. image:: _images/article_actions_message.png
+    
+Actions that provide intermediate pages
+---------------------------------------
+
+By default, after an action is performed the user is simply redirected back
+to the original change list page. However, some actions, especially more
+complex ones, will need to return intermediate pages. For example, the
+built-in delete action asks for confirmation before deleting the selected
+objects.
+
+To provide an intermediary page, simply return an
+:class:`~django.http.HttpResponse` (or subclass) from your action. For
+example, you might write a simple export function that uses Django's
+:doc:`serialization functions </topics/serialization>` to dump some selected
+objects as JSON::
+
+    from django.http import HttpResponse
+    from django.core import serializers
+
+    def export_as_json(modeladmin, request, queryset):
+        response = HttpResponse(mimetype="text/javascript")
+        serializers.serialize("json", queryset, stream=response)
+        return response
+
+Generally, something like the above isn't considered a great idea. Most of the
+time, the best practice will be to return an
+:class:`~django.http.HttpResponseRedirect` and redirect the user to a view
+you've written, passing the list of selected objects in the GET query string.
+This allows you to provide complex interaction logic on the intermediary
+pages. For example, if you wanted to provide a more complete export function,
+you'd want to let the user choose a format, and possibly a list of fields to
+include in the export. The best thing to do would be to write a small action
+that simply redirects to your custom export view::
+
+    from django.contrib import admin
+    from django.contrib.contenttypes.models import ContentType
+    from django.http import HttpResponseRedirect
+    
+    def export_selected_objects(modeladmin, request, queryset):
+        selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME)
+        ct = ContentType.objects.get_for_model(queryset.model)
+        return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected)))
+
+As you can see, the action is the simple part; all the complex logic would
+belong in your export view. This would need to deal with objects of any type,
+hence the business with the ``ContentType``.
+
+Writing this view is left as an exercise to the reader.
+
+.. _adminsite-actions:
+
+Making actions available site-wide
+----------------------------------
+
+.. method:: AdminSite.add_action(action[, name])
+
+    Some actions are best if they're made available to *any* object in the admin
+    site -- the export action defined above would be a good candidate. You can
+    make an action globally available using :meth:`AdminSite.add_action()`. For
+    example::
+
+        from django.contrib import admin
+        
+        admin.site.add_action(export_selected_objects)
+
+    This makes the `export_selected_objects` action globally available as an
+    action named `"export_selected_objects"`. You can explicitly give the action
+    a name -- good if you later want to programatically :ref:`remove the action
+    <disabling-admin-actions>` -- by passing a second argument to
+    :meth:`AdminSite.add_action()`::
+    
+        admin.site.add_action(export_selected_objects, 'export_selected')
+
+.. _disabling-admin-actions:
+
+Disabling actions
+-----------------
+
+Sometimes you need to disable certain actions -- especially those
+:ref:`registered site-wide <adminsite-actions>` -- for particular objects.
+There's a few ways you can disable actions:
+
+Disabling a site-wide action
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. method:: AdminSite.disable_action(name)
+
+    If you need to disable a :ref:`site-wide action <adminsite-actions>` you can
+    call :meth:`AdminSite.disable_action()`.
+    
+    For example, you can use this method to remove the built-in "delete selected
+    objects" action::
+    
+        admin.site.disable_action('delete_selected')
+        
+    Once you've done the above, that action will no longer be available
+    site-wide.
+    
+    If, however, you need to re-enable a globally-disabled action for one
+    particular model, simply list it explicitly in your ``ModelAdmin.actions``
+    list::
+    
+        # Globally disable delete selected
+        admin.site.disable_action('delete_selected')
+        
+        # This ModelAdmin will not have delete_selected available
+        class SomeModelAdmin(admin.ModelAdmin):
+            actions = ['some_other_action']
+            ...
+            
+        # This one will
+        class AnotherModelAdmin(admin.ModelAdmin):
+            actions = ['delete_selected', 'a_third_action']
+            ...
+            
+
+Disabling all actions for a particular :class:`ModelAdmin`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply
+set :attr:`ModelAdmin.actions` to ``None``::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        actions = None
+        
+This tells the :class:`ModelAdmin` to not display or allow any actions,
+including any :ref:`site-wide actions <adminsite-actions>`.
+
+Conditionally enabling or disabling actions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. method:: ModelAdmin.get_actions(request)
+
+    Finally, you can conditionally enable or disable actions on a per-request 
+    (and hence per-user basis) by overriding :meth:`ModelAdmin.get_actions`.
+
+    This returns a dictionary of actions allowed. The keys are action names, and
+    the values are ``(function, name, short_description)`` tuples.
+
+    Most of the time you'll use this method to conditionally remove actions from
+    the list gathered by the superclass. For example, if I only wanted users
+    whose names begin with 'J' to be able to delete objects in bulk, I could do
+    the following::
+    
+        class MyModelAdmin(admin.ModelAdmin):
+            ...
+            
+            def get_actions(self, request):
+                actions = super(MyModelAdmin, self).get_actions(request)
+                if request.user.username[0].upper() != 'J':
+                    del actions['delete_selected']
+                return actions
+    
+
diff --git a/parts/django/docs/ref/contrib/admin/admindocs.txt b/parts/django/docs/ref/contrib/admin/admindocs.txt
new file mode 100644
index 0000000..6743921
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/admindocs.txt
@@ -0,0 +1,161 @@
+========================================

+The Django admin documentation generator

+========================================

+

+.. module:: django.contrib.admindocs

+    :synopsis: Django's admin documentation generator.

+

+.. currentmodule:: django.contrib.admindocs

+

+Django's :mod:`~django.contrib.admindocs` app pulls documentation from the

+docstrings of models, views, template tags, and template filters for any app in

+:setting:`INSTALLED_APPS` and makes that documentation available from the

+:mod:`Django admin <django.contrib.admin>`.

+

+In addition to providing offline documentation for all template tags and

+template filters that ship with Django, you may utilize admindocs to quickly

+document your own code.

+

+Overview

+========

+

+To activate the :mod:`~django.contrib.admindocs`, you will need to do

+the following:

+

+    * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.

+    * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to

+      your :data:`urlpatterns`. Make sure it's included *before* the

+      ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get

+      handled by the latter entry.

+    * Install the docutils Python module (http://docutils.sf.net/).

+    * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR`

+      setting to be configured.

+    * **Optional:** Using the admindocs bookmarklets requires the

+      :mod:`XViewMiddleware<django.middleware.doc>` to be installed.

+

+Once those steps are complete, you can start browsing the documentation by

+going to your admin interface and clicking the "Documentation" link in the

+upper right of the page.

+

+Documentation helpers

+=====================

+

+The following special markup can be used in your docstrings to easily create

+hyperlinks to other components:

+

+=================   =======================

+Django Component    reStructuredText roles

+=================   =======================

+Models              ``:model:`appname.ModelName```

+Views               ``:view:`appname.view_name```

+Template tags       ``:tag:`tagname```

+Template filters    ``:filter:`filtername```

+Templates           ``:template:`path/to/template.html```

+=================   =======================

+

+Model reference

+===============

+

+The **models** section of the ``admindocs`` page describes each model in the

+system along with all the fields and methods available on it. Relationships to

+other models appear as hyperlinks. Descriptions are pulled from ``help_text``

+attributes on fields or from docstrings on model methods.

+

+A model with useful documentation might look like this::

+

+    class BlogEntry(models.Model):

+        """

+        Stores a single blog entry, related to :model:`blog.Blog` and

+        :model:`auth.User`.

+

+        """

+        slug = models.SlugField(help_text="A short label, generally used in URLs.")

+        author = models.ForeignKey(User)

+        blog = models.ForeignKey(Blog)

+        ...

+

+        def publish(self):

+            """Makes the blog entry live on the site."""

+            ...

+

+View reference

+==============

+

+Each URL in your site has a separate entry in the ``admindocs`` page, and

+clicking on a given URL will show you the corresponding view. Helpful things

+you can document in your view function docstrings include:

+

+    * A short description of what the view does.

+    * The **context**, or a list of variables available in the view's template.

+    * The name of the template or templates that are used for that view.

+

+For example::

+

+    from myapp.models import MyModel

+

+    def my_view(request, slug):

+        """

+        Display an individual :model:`myapp.MyModel`.

+

+        **Context**

+

+        ``RequestContext``

+

+        ``mymodel``

+            An instance of :model:`myapp.MyModel`.

+

+        **Template:**

+

+        :template:`myapp/my_template.html`

+

+        """

+        return render_to_response('myapp/my_template.html', {

+            'mymodel': MyModel.objects.get(slug=slug)

+        }, context_instance=RequestContext(request))

+

+

+Template tags and filters reference

+===================================

+

+The **tags** and **filters** ``admindocs`` sections describe all the tags and

+filters that come with Django (in fact, the :ref:`built-in tag reference

+<ref-templates-builtins-tags>` and :ref:`built-in filter reference

+<ref-templates-builtins-filters>` documentation come directly from those

+pages). Any tags or filters that you create or are added by a third-party app

+will show up in these sections as well.

+

+

+Template reference

+==================

+

+While ``admindocs`` does not include a place to document templates by

+themselves, if you use the ``:template:`path/to/template.html``` syntax in a

+docstring the resulting page will verify the path of that template with

+Django's :ref:`template loaders <template-loaders>`. This can be a handy way to

+check if the specified template exists and to show where on the filesystem that

+template is stored.

+

+

+Included Bookmarklets

+=====================

+

+Several useful bookmarklets are available from the ``admindocs`` page:

+

+    Documentation for this page

+        Jumps you from any page to the documentation for the view that generates

+        that page.

+

+    Show object ID

+        Shows the content-type and unique ID for pages that represent a single

+        object.

+

+    Edit this object

+        Jumps to the admin page for pages that represent a single object.

+

+Using these bookmarklets requires that you are either logged into the

+:mod:`Django admin <django.contrib.admin>` as a

+:class:`~django.contrib.auth.models.User` with

+:attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or

+that the :mod:`django.middleware.doc` middleware and

+:mod:`XViewMiddleware <django.middleware.doc>` are installed and you

+are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.

diff --git a/parts/django/docs/ref/contrib/admin/index.txt b/parts/django/docs/ref/contrib/admin/index.txt
new file mode 100644
index 0000000..b99cfdc
--- /dev/null
+++ b/parts/django/docs/ref/contrib/admin/index.txt
@@ -0,0 +1,1613 @@
+=====================
+The Django admin site
+=====================
+
+.. module:: django.contrib.admin
+   :synopsis: Django's admin site.
+
+One of the most powerful parts of Django is the automatic admin interface. It
+reads metadata in your model to provide a powerful and production-ready
+interface that content producers can immediately use to start adding content to
+the site. In this document, we discuss how to activate, use and customize
+Django's admin interface.
+
+.. admonition:: Note
+
+    The admin site has been refactored significantly since Django 0.96. This
+    document describes the newest version of the admin site, which allows for
+    much richer customization. If you follow the development of Django itself,
+    you may have heard this described as "newforms-admin."
+
+Overview
+========
+
+There are six steps in activating the Django admin site:
+
+    1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
+       setting.
+
+    2. Admin has two dependencies - ``django.contrib.auth`` and
+       ``django.contrib.contenttypes``. If these applications are not
+       in your :setting:`INSTALLED_APPS` list, add them.
+
+    3. Determine which of your application's models should be editable in the
+       admin interface.
+
+    4. For each of those models, optionally create a ``ModelAdmin`` class that
+       encapsulates the customized admin functionality and options for that
+       particular model.
+
+    5. Instantiate an ``AdminSite`` and tell it about each of your models and
+       ``ModelAdmin`` classes.
+
+    6. Hook the ``AdminSite`` instance into your URLconf.
+
+Other topics
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   actions
+   admindocs
+
+.. seealso::
+
+    For information about serving the media files (images, JavaScript, and CSS)
+    associated with the admin in production, see :ref:`serving-media-files`.
+
+``ModelAdmin`` objects
+======================
+
+.. class:: ModelAdmin
+
+The ``ModelAdmin`` class is the representation of a model in the admin
+interface. These are stored in a file named ``admin.py`` in your application.
+Let's take a look at a very simple example of the ``ModelAdmin``::
+
+    from django.contrib import admin
+    from myproject.myapp.models import Author
+
+    class AuthorAdmin(admin.ModelAdmin):
+        pass
+    admin.site.register(Author, AuthorAdmin)
+
+.. admonition:: Do you need a ``ModelAdmin`` object at all?
+
+    In the preceding example, the ``ModelAdmin`` class doesn't define any
+    custom values (yet). As a result, the default admin interface will be
+    provided. If you are happy with the default admin interface, you don't
+    need to define a ``ModelAdmin`` object at all -- you can register the
+    model class without providing a ``ModelAdmin`` description. The
+    preceding example could be simplified to::
+
+        from django.contrib import admin
+        from myproject.myapp.models import Author
+
+        admin.site.register(Author)
+
+``ModelAdmin`` Options
+----------------------
+
+The ``ModelAdmin`` is very flexible. It has several options for dealing with
+customizing the interface. All options are defined on the ``ModelAdmin``
+subclass::
+
+    class AuthorAdmin(admin.ModelAdmin):
+        date_hierarchy = 'pub_date'
+
+.. attribute:: ModelAdmin.date_hierarchy
+
+Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
+your model, and the change list page will include a date-based drilldown
+navigation by that field.
+
+Example::
+
+    date_hierarchy = 'pub_date'
+
+.. attribute:: ModelAdmin.form
+
+By default a ``ModelForm`` is dynamically created for your model. It is used
+to create the form presented on both the add/change pages. You can easily
+provide your own ``ModelForm`` to override any default form behavior on the
+add/change pages.
+
+For an example see the section `Adding custom validation to the admin`_.
+
+.. attribute:: ModelAdmin.fieldsets
+
+Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
+
+``fieldsets`` is a list of two-tuples, in which each two-tuple represents a
+``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the
+form.)
+
+The two-tuples are in the format ``(name, field_options)``, where ``name`` is a
+string representing the title of the fieldset and ``field_options`` is a
+dictionary of information about the fieldset, including a list of fields to be
+displayed in it.
+
+A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
+
+    class FlatPageAdmin(admin.ModelAdmin):
+        fieldsets = (
+            (None, {
+                'fields': ('url', 'title', 'content', 'sites')
+            }),
+            ('Advanced options', {
+                'classes': ('collapse',),
+                'fields': ('enable_comments', 'registration_required', 'template_name')
+            }),
+        )
+
+This results in an admin page that looks like:
+
+    .. image:: _images/flatfiles_admin.png
+
+If ``fieldsets`` isn't given, Django will default to displaying each field
+that isn't an ``AutoField`` and has ``editable=True``, in a single fieldset,
+in the same order as the fields are defined in the model.
+
+The ``field_options`` dictionary can have the following keys:
+
+    * ``fields``
+        A tuple of field names to display in this fieldset. This key is
+        required.
+
+        Example::
+
+            {
+            'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
+            }
+
+        To display multiple fields on the same line, wrap those fields in
+        their own tuple. In this example, the ``first_name`` and ``last_name``
+        fields will display on the same line::
+
+            {
+            'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
+            }
+
+        .. versionadded:: 1.2
+
+        ``fields`` can contain values defined in
+        :attr:`ModelAdmin.readonly_fields` to be displayed as read-only.
+
+    * ``classes``
+        A list containing extra CSS classes to apply to the fieldset.
+
+        Example::
+
+            {
+            'classes': ['wide', 'extrapretty'],
+            }
+
+        Two useful classes defined by the default admin site stylesheet are
+        ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will
+        be initially collapsed in the admin and replaced with a small
+        "click to expand" link. Fieldsets with the ``wide`` style will be
+        given extra horizontal space.
+
+    * ``description``
+        A string of optional extra text to be displayed at the top of each
+        fieldset, under the heading of the fieldset.
+
+        Note that this value is *not* HTML-escaped when it's displayed in
+        the admin interface. This lets you include HTML if you so desire.
+        Alternatively you can use plain text and
+        ``django.utils.html.escape()`` to escape any HTML special
+        characters.
+
+.. attribute:: ModelAdmin.fields
+
+Use this option as an alternative to ``fieldsets`` if the layout does not
+matter and if you want to only show a subset of the available fields in the
+form. For example, you could define a simpler version of the admin form for
+the ``django.contrib.flatpages.FlatPage`` model as follows::
+
+    class FlatPageAdmin(admin.ModelAdmin):
+        fields = ('url', 'title', 'content')
+
+In the above example, only the fields 'url', 'title' and 'content' will be
+displayed, sequentially, in the form.
+
+.. versionadded:: 1.2
+
+``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
+to be displayed as read-only.
+
+.. admonition:: Note
+
+    This ``fields`` option should not be confused with the ``fields``
+    dictionary key that is within the ``fieldsets`` option, as described in
+    the previous section.
+
+.. attribute:: ModelAdmin.exclude
+
+This attribute, if given, should be a list of field names to exclude from the
+form.
+
+For example, let's consider the following model::
+
+    class Author(models.Model):
+        name = models.CharField(max_length=100)
+        title = models.CharField(max_length=3)
+        birth_date = models.DateField(blank=True, null=True)
+
+If you want a form for the ``Author`` model that includes only the ``name``
+and ``title`` fields, you would specify ``fields`` or ``exclude`` like this::
+
+    class AuthorAdmin(admin.ModelAdmin):
+        fields = ('name', 'title')
+
+    class AuthorAdmin(admin.ModelAdmin):
+        exclude = ('birth_date',)
+
+Since the Author model only has three fields, ``name``, ``title``, and
+``birth_date``, the forms resulting from the above declarations will contain
+exactly the same fields.
+
+.. attribute:: ModelAdmin.filter_horizontal
+
+Use a nifty unobtrusive JavaScript "filter" interface instead of the
+usability-challenged ``<select multiple>`` in the admin form. The value is a
+list of fields that should be displayed as a horizontal filter interface. See
+``filter_vertical`` to use a vertical interface.
+
+.. attribute:: ModelAdmin.filter_vertical
+
+Same as ``filter_horizontal``, but is a vertical display of the filter
+interface.
+
+.. attribute:: ModelAdmin.list_display
+
+Set ``list_display`` to control which fields are displayed on the change list
+page of the admin.
+
+Example::
+
+    list_display = ('first_name', 'last_name')
+
+If you don't set ``list_display``, the admin site will display a single column
+that displays the ``__unicode__()`` representation of each object.
+
+You have four possible values that can be used in ``list_display``:
+
+    * A field of the model. For example::
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = ('first_name', 'last_name')
+
+    * A callable that accepts one parameter for the model instance. For
+      example::
+
+          def upper_case_name(obj):
+              return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+          upper_case_name.short_description = 'Name'
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = (upper_case_name,)
+
+    * A string representing an attribute on the ``ModelAdmin``. This behaves
+      same as the callable. For example::
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = ('upper_case_name',)
+
+              def upper_case_name(self, obj):
+                return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+              upper_case_name.short_description = 'Name'
+
+    * A string representing an attribute on the model. This behaves almost
+      the same as the callable, but ``self`` in this context is the model
+      instance. Here's a full model example::
+
+          class Person(models.Model):
+              name = models.CharField(max_length=50)
+              birthday = models.DateField()
+
+              def decade_born_in(self):
+                  return self.birthday.strftime('%Y')[:3] + "0's"
+              decade_born_in.short_description = 'Birth decade'
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = ('name', 'decade_born_in')
+
+A few special cases to note about ``list_display``:
+
+    * If the field is a ``ForeignKey``, Django will display the
+      ``__unicode__()`` of the related object.
+
+    * ``ManyToManyField`` fields aren't supported, because that would entail
+      executing a separate SQL statement for each row in the table. If you
+      want to do this nonetheless, give your model a custom method, and add
+      that method's name to ``list_display``. (See below for more on custom
+      methods in ``list_display``.)
+
+    * If the field is a ``BooleanField`` or ``NullBooleanField``, Django will
+      display a pretty "on" or "off" icon instead of ``True`` or ``False``.
+
+    * If the string given is a method of the model, ``ModelAdmin`` or a
+      callable, Django will HTML-escape the output by default. If you'd rather
+      not escape the output of the method, give the method an ``allow_tags``
+      attribute whose value is ``True``.
+
+      Here's a full example model::
+
+          class Person(models.Model):
+              first_name = models.CharField(max_length=50)
+              last_name = models.CharField(max_length=50)
+              color_code = models.CharField(max_length=6)
+
+              def colored_name(self):
+                  return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
+              colored_name.allow_tags = True
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = ('first_name', 'last_name', 'colored_name')
+
+    * If the string given is a method of the model, ``ModelAdmin`` or a
+      callable that returns True or False Django will display a pretty "on" or
+      "off" icon if you give the method a ``boolean`` attribute whose value is
+      ``True``.
+
+      Here's a full example model::
+
+          class Person(models.Model):
+              first_name = models.CharField(max_length=50)
+              birthday = models.DateField()
+
+              def born_in_fifties(self):
+                  return self.birthday.strftime('%Y')[:3] == '195'
+              born_in_fifties.boolean = True
+
+          class PersonAdmin(admin.ModelAdmin):
+              list_display = ('name', 'born_in_fifties')
+
+
+    * The ``__str__()`` and ``__unicode__()`` methods are just as valid in
+      ``list_display`` as any other model method, so it's perfectly OK to do
+      this::
+
+          list_display = ('__unicode__', 'some_other_field')
+
+    * Usually, elements of ``list_display`` that aren't actual database fields
+      can't be used in sorting (because Django does all the sorting at the
+      database level).
+
+      However, if an element of ``list_display`` represents a certain database
+      field, you can indicate this fact by setting the ``admin_order_field``
+      attribute of the item.
+
+      For example::
+
+        class Person(models.Model):
+            first_name = models.CharField(max_length=50)
+            color_code = models.CharField(max_length=6)
+
+            def colored_first_name(self):
+                return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
+            colored_first_name.allow_tags = True
+            colored_first_name.admin_order_field = 'first_name'
+
+        class PersonAdmin(admin.ModelAdmin):
+            list_display = ('first_name', 'colored_first_name')
+
+      The above will tell Django to order by the ``first_name`` field when
+      trying to sort by ``colored_first_name`` in the admin.
+
+.. attribute:: ModelAdmin.list_display_links
+
+Set ``list_display_links`` to control which fields in ``list_display`` should
+be linked to the "change" page for an object.
+
+By default, the change list page will link the first column -- the first field
+specified in ``list_display`` -- to the change page for each item. But
+``list_display_links`` lets you change which columns are linked. Set
+``list_display_links`` to a list or tuple of field names (in the same format as
+``list_display``) to link.
+
+``list_display_links`` can specify one or many field names. As long as the
+field names appear in ``list_display``, Django doesn't care how many (or how
+few) fields are linked. The only requirement is: If you want to use
+``list_display_links``, you must define ``list_display``.
+
+In this example, the ``first_name`` and ``last_name`` fields will be linked on
+the change list page::
+
+    class PersonAdmin(admin.ModelAdmin):
+        list_display = ('first_name', 'last_name', 'birthday')
+        list_display_links = ('first_name', 'last_name')
+
+.. _admin-list-editable:
+
+.. attribute:: ModelAdmin.list_editable
+
+.. versionadded:: 1.1
+
+Set ``list_editable`` to a list of field names on the model which will allow
+editing on the change list page. That is, fields listed in ``list_editable``
+will be displayed as form widgets on the change list page, allowing users to
+edit and save multiple rows at once.
+
+.. note::
+
+    ``list_editable`` interacts with a couple of other options in particular
+    ways; you should note the following rules:
+
+        * Any field in ``list_editable`` must also be in ``list_display``. You
+          can't edit a field that's not displayed!
+
+        * The same field can't be listed in both ``list_editable`` and
+          ``list_display_links`` -- a field can't be both a form and a link.
+
+    You'll get a validation error if either of these rules are broken.
+
+.. attribute:: ModelAdmin.list_filter
+
+Set ``list_filter`` to activate filters in the right sidebar of the change list
+page of the admin. This should be a list of field names, and each specified
+field should be either a ``BooleanField``, ``CharField``, ``DateField``,
+``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
+
+This example, taken from the ``django.contrib.auth.models.User`` model, shows
+how both ``list_display`` and ``list_filter`` work::
+
+    class UserAdmin(admin.ModelAdmin):
+        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
+        list_filter = ('is_staff', 'is_superuser')
+
+The above code results in an admin change list page that looks like this:
+
+    .. image:: _images/users_changelist.png
+
+(This example also has ``search_fields`` defined. See below.)
+
+.. attribute:: ModelAdmin.list_per_page
+
+Set ``list_per_page`` to control how many items appear on each paginated admin
+change list page. By default, this is set to ``100``.
+
+.. attribute:: ModelAdmin.list_select_related
+
+Set ``list_select_related`` to tell Django to use
+:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of
+objects on the admin change list page. This can save you a bunch of database
+queries.
+
+The value should be either ``True`` or ``False``. Default is ``False``.
+
+Note that Django will use :meth:`~django.db.models.QuerySet.select_related`,
+regardless of this setting, if one of the ``list_display`` fields is a
+``ForeignKey``.
+
+.. attribute:: ModelAdmin.inlines
+
+See ``InlineModelAdmin`` objects below.
+
+.. attribute:: ModelAdmin.ordering
+
+Set ``ordering`` to specify how objects on the admin change list page should be
+ordered. This should be a list or tuple in the same format as a model's
+``ordering`` parameter.
+
+If this isn't provided, the Django admin will use the model's default ordering.
+
+.. admonition:: Note
+
+    Django will only honor the first element in the list/tuple; any others
+    will be ignored.
+
+.. attribute:: ModelAdmin.prepopulated_fields
+
+Set ``prepopulated_fields`` to a dictionary mapping field names to the fields
+it should prepopulate from::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        prepopulated_fields = {"slug": ("title",)}
+
+When set, the given fields will use a bit of JavaScript to populate from the
+fields assigned. The main use for this functionality is to automatically
+generate the value for ``SlugField`` fields from one or more other fields. The
+generated value is produced by concatenating the values of the source fields,
+and then by transforming that result into a valid slug (e.g. substituting
+dashes for spaces).
+
+``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor
+``ManyToManyField`` fields.
+
+.. attribute:: ModelAdmin.radio_fields
+
+By default, Django's admin uses a select-box interface (<select>) for
+fields that are ``ForeignKey`` or have ``choices`` set. If a field is present
+in ``radio_fields``, Django will use a radio-button interface instead.
+Assuming ``group`` is a ``ForeignKey`` on the ``Person`` model::
+
+    class PersonAdmin(admin.ModelAdmin):
+        radio_fields = {"group": admin.VERTICAL}
+
+You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
+``django.contrib.admin`` module.
+
+Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
+``choices`` set.
+
+.. attribute:: ModelAdmin.raw_id_fields
+
+By default, Django's admin uses a select-box interface (<select>) for
+fields that are ``ForeignKey``. Sometimes you don't want to incur the
+overhead of having to select all the related instances to display in the
+drop-down.
+
+``raw_id_fields`` is a list of fields you would like to change
+into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        raw_id_fields = ("newspaper",)
+
+.. attribute:: ModelAdmin.readonly_fields
+
+.. versionadded:: 1.2
+
+By default the admin shows all fields as editable. Any fields in this option
+(which should be a ``list`` or ``tuple``) will display its data as-is and
+non-editable. This option behaves nearly identical to :attr:`ModelAdmin.list_display`.
+Usage is the same, however, when you specify :attr:`ModelAdmin.fields` or
+:attr:`ModelAdmin.fieldsets` the read-only fields must be present to be shown
+(they are ignored otherwise).
+
+If ``readonly_fields`` is used without defining explicit ordering through
+:attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` they will be added
+last after all editable fields.
+
+.. attribute:: ModelAdmin.save_as
+
+Set ``save_as`` to enable a "save as" feature on admin change forms.
+
+Normally, objects have three save options: "Save", "Save and continue editing"
+and "Save and add another". If ``save_as`` is ``True``, "Save and add another"
+will be replaced by a "Save as" button.
+
+"Save as" means the object will be saved as a new object (with a new ID),
+rather than the old object.
+
+By default, ``save_as`` is set to ``False``.
+
+.. attribute:: ModelAdmin.save_on_top
+
+Set ``save_on_top`` to add save buttons across the top of your admin change
+forms.
+
+Normally, the save buttons appear only at the bottom of the forms. If you set
+``save_on_top``, the buttons will appear both on the top and the bottom.
+
+By default, ``save_on_top`` is set to ``False``.
+
+.. attribute:: ModelAdmin.search_fields
+
+Set ``search_fields`` to enable a search box on the admin change list page.
+This should be set to a list of field names that will be searched whenever
+somebody submits a search query in that text box.
+
+These fields should be some kind of text field, such as ``CharField`` or
+``TextField``. You can also perform a related lookup on a ``ForeignKey`` or
+``ManyToManyField`` with the lookup API "follow" notation::
+
+    search_fields = ['foreign_key__related_fieldname']
+
+For example, if you have a blog entry with an author, the following definition
+would enable search blog entries by the email address of the author::
+
+    search_fields = ['user__email']
+
+When somebody does a search in the admin search box, Django splits the search
+query into words and returns all objects that contain each of the words, case
+insensitive, where each word must be in at least one of ``search_fields``. For
+example, if ``search_fields`` is set to ``['first_name', 'last_name']`` and a
+user searches for ``john lennon``, Django will do the equivalent of this SQL
+``WHERE`` clause::
+
+    WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
+    AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
+
+For faster and/or more restrictive searches, prefix the field name
+with an operator:
+
+``^``
+    Matches the beginning of the field. For example, if ``search_fields`` is
+    set to ``['^first_name', '^last_name']`` and a user searches for
+    ``john lennon``, Django will do the equivalent of this SQL ``WHERE``
+    clause::
+
+        WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%')
+        AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%')
+
+    This query is more efficient than the normal ``'%john%'`` query, because
+    the database only needs to check the beginning of a column's data, rather
+    than seeking through the entire column's data. Plus, if the column has an
+    index on it, some databases may be able to use the index for this query,
+    even though it's a ``LIKE`` query.
+
+``=``
+    Matches exactly, case-insensitive. For example, if
+    ``search_fields`` is set to ``['=first_name', '=last_name']`` and
+    a user searches for ``john lennon``, Django will do the equivalent
+    of this SQL ``WHERE`` clause::
+
+        WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john')
+        AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon')
+
+    Note that the query input is split by spaces, so, following this example,
+    it's currently not possible to search for all records in which
+    ``first_name`` is exactly ``'john winston'`` (containing a space).
+
+``@``
+    Performs a full-text match. This is like the default search method but uses
+    an index. Currently this is only available for MySQL.
+
+.. attribute:: ModelAdmin.formfield_overrides
+
+.. versionadded:: 1.1
+
+This provides a quick-and-dirty way to override some of the
+:class:`~django.forms.Field` options for use in the admin.
+``formfield_overrides`` is a dictionary mapping a field class to a dict of
+arguments to pass to the field at construction time.
+
+Since that's a bit abstract, let's look at a concrete example. The most common
+use of ``formfield_overrides`` is to add a custom widget for a certain type of
+field. So, imagine we've written a ``RichTextEditorWidget`` that we'd like to
+use for large text fields instead of the default ``<textarea>``. Here's how we'd
+do that::
+
+    from django.db import models
+    from django.contrib import admin
+
+    # Import our custom widget and our model from where they're defined
+    from myapp.widgets import RichTextEditorWidget
+    from myapp.models import MyModel
+
+    class MyModelAdmin(admin.ModelAdmin):
+        formfield_overrides = {
+            models.TextField: {'widget': RichTextEditorWidget},
+        }
+
+Note that the key in the dictionary is the actual field class, *not* a string.
+The value is another dictionary; these arguments will be passed to
+:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for details.
+
+.. warning::
+
+    If you want to use a custom widget with a relation field (i.e.
+    :class:`~django.db.models.ForeignKey` or
+    :class:`~django.db.models.ManyToManyField`), make sure you haven't included
+    that field's name in ``raw_id_fields`` or ``radio_fields``.
+
+    ``formfield_overrides`` won't let you change the widget on relation fields
+    that have ``raw_id_fields`` or ``radio_fields`` set. That's because
+    ``raw_id_fields`` and ``radio_fields`` imply custom widgets of their own.
+
+.. attribute:: ModelAdmin.actions
+
+.. versionadded:: 1.1
+
+A list of actions to make available on the change list page. See
+:doc:`/ref/contrib/admin/actions` for details.
+
+.. attribute:: ModelAdmin.actions_on_top
+.. attribute:: ModelAdmin.actions_on_bottom
+
+.. versionadded:: 1.1
+
+Controls where on the page the actions bar appears. By default, the admin
+changelist displays actions at the top of the page (``actions_on_top = True;
+actions_on_bottom = False``).
+
+.. attribute:: ModelAdmin.actions_selection_counter
+
+.. versionadded:: 1.2
+
+Controls whether a selection counter is display next to the action dropdown.
+By default, the admin changelist will display it
+(``actions_selection_counter = True``).
+
+Custom template options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The `Overriding Admin Templates`_ section describes how to override or extend
+the default admin templates.  Use the following options to override the default
+templates used by the :class:`ModelAdmin` views:
+
+.. attribute:: ModelAdmin.add_form_template
+
+    .. versionadded:: 1.2
+
+    Path to a custom template, used by :meth:`add_view`.
+
+.. attribute:: ModelAdmin.change_form_template
+
+    Path to a custom template, used by :meth:`change_view`.
+
+.. attribute:: ModelAdmin.change_list_template
+
+    Path to a custom template, used by :meth:`changelist_view`.
+
+.. attribute:: ModelAdmin.delete_confirmation_template
+
+    Path to a custom template, used by :meth:`delete_view` for displaying a
+    confirmation page when deleting one or more objects.
+
+.. attribute:: ModelAdmin.delete_selected_confirmation_template
+
+    .. versionadded:: 1.2
+
+    Path to a custom template, used by the :meth:`delete_selected`
+    action method for displaying a confirmation page when deleting one
+    or more objects. See the :doc:`actions
+    documentation</ref/contrib/admin/actions>`.
+
+.. attribute:: ModelAdmin.object_history_template
+
+    Path to a custom template, used by :meth:`history_view`.
+
+
+.. _model-admin-methods:
+
+``ModelAdmin`` methods
+----------------------
+
+.. method:: ModelAdmin.save_model(self, request, obj, form, change)
+
+The ``save_model`` method is given the ``HttpRequest``, a model instance,
+a ``ModelForm`` instance and a boolean value based on whether it is adding or
+changing the object. Here you can do any pre- or post-save operations.
+
+For example to attach ``request.user`` to the object prior to saving::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        def save_model(self, request, obj, form, change):
+            obj.user = request.user
+            obj.save()
+
+.. method:: ModelAdmin.save_formset(self, request, form, formset, change)
+
+The ``save_formset`` method is given the ``HttpRequest``, the parent
+``ModelForm`` instance and a boolean value based on whether it is adding or
+changing the parent object.
+
+For example to attach ``request.user`` to each changed formset
+model instance::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        def save_formset(self, request, form, formset, change):
+            instances = formset.save(commit=False)
+            for instance in instances:
+                instance.user = request.user
+                instance.save()
+            formset.save_m2m()
+
+.. method:: ModelAdmin.get_readonly_fields(self, request, obj=None)
+
+.. versionadded:: 1.2
+
+The ``get_readonly_fields`` method is given the ``HttpRequest`` and the
+``obj`` being edited (or ``None`` on an add form) and is expected to return a
+``list`` or ``tuple`` of field names that will be displayed as read-only, as
+described above in the :attr:`ModelAdmin.readonly_fields` section.
+
+.. method:: ModelAdmin.get_urls(self)
+
+.. versionadded:: 1.1
+
+The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for
+that ModelAdmin in the same way as a URLconf.  Therefore you can extend them as
+documented in :doc:`/topics/http/urls`::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def get_urls(self):
+            urls = super(MyModelAdmin, self).get_urls()
+            my_urls = patterns('',
+                (r'^my_view/$', self.my_view)
+            )
+            return my_urls + urls
+
+.. note::
+
+    Notice that the custom patterns are included *before* the regular admin
+    URLs: the admin URL patterns are very permissive and will match nearly
+    anything, so you'll usually want to prepend your custom URLs to the built-in
+    ones.
+
+However, the ``self.my_view`` function registered above suffers from two
+problems:
+
+  * It will *not* perform any permission checks, so it will be accessible to
+    the general public.
+  * It will *not* provide any header details to prevent caching. This means if
+    the page retrieves data from the database, and caching middleware is
+    active, the page could show outdated information.
+
+Since this is usually not what you want, Django provides a convenience wrapper
+to check permissions and mark the view as non-cacheable. This wrapper is
+:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a
+``ModelAdmin`` instance); use it like so::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def get_urls(self):
+            urls = super(MyModelAdmin, self).get_urls()
+            my_urls = patterns('',
+                (r'^my_view/$', self.admin_site.admin_view(self.my_view))
+            )
+            return my_urls + urls
+
+Notice the wrapped view in the fifth line above::
+
+    (r'^my_view/$', self.admin_site.admin_view(self.my_view))
+
+This wrapping will protect ``self.my_view`` from unauthorized access and will
+apply the ``django.views.decorators.cache.never_cache`` decorator to make sure
+it is not cached if the cache middleware is active.
+
+If the page is cacheable, but you still want the permission check to be performed,
+you can pass a ``cacheable=True`` argument to :meth:`AdminSite.admin_view`::
+
+    (r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True))
+
+.. method:: ModelAdmin.formfield_for_foreignkey(self, db_field, request, **kwargs)
+
+.. versionadded:: 1.1
+
+The ``formfield_for_foreignkey`` method on a ``ModelAdmin`` allows you to
+override the default formfield for a foreign key field. For example, to
+return a subset of objects for this foreign key field based on the user::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def formfield_for_foreignkey(self, db_field, request, **kwargs):
+            if db_field.name == "car":
+                kwargs["queryset"] = Car.objects.filter(owner=request.user)
+            return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs)
+
+This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field
+to only display the cars owned by the ``User`` instance.
+
+.. method:: ModelAdmin.formfield_for_manytomany(self, db_field, request, **kwargs)
+
+.. versionadded:: 1.1
+
+Like the ``formfield_for_foreignkey`` method, the ``formfield_for_manytomany``
+method can be overridden to change the default formfield for a many to many
+field. For example, if an owner can own multiple cars and cars can belong
+to multiple owners -- a many to many relationship -- you could filter the
+``Car`` foreign key field to only display the cars owned by the ``User``::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def formfield_for_manytomany(self, db_field, request, **kwargs):
+            if db_field.name == "cars":
+                kwargs["queryset"] = Car.objects.filter(owner=request.user)
+            return super(MyModelAdmin, self).formfield_for_manytomany(db_field, request, **kwargs)
+
+.. method:: ModelAdmin.queryset(self, request)
+
+The ``queryset`` method on a ``ModelAdmin`` returns a
+:class:`~django.db.models.QuerySet` of all model instances that can be
+edited by the admin site. One use case for overriding this method is
+to show objects owned by the logged-in user::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def queryset(self, request):
+            qs = super(MyModelAdmin, self).queryset(request)
+            if request.user.is_superuser:
+                return qs
+            return qs.filter(author=request.user)
+
+.. method:: ModelAdmin.message_user(request, message)
+
+    Sends a message to the user. The default implementation creates a message
+    using the :mod:`django.contrib.messages` backend. See the
+    :ref:`custom ModelAdmin example <custom-admin-action>`.
+
+Other methods
+~~~~~~~~~~~~~
+
+.. method:: ModelAdmin.add_view(self, request, form_url='', extra_context=None)
+
+Django view for the model instance addition page. See note below.
+
+.. method:: ModelAdmin.change_view(self, request, object_id, extra_context=None)
+
+Django view for the model instance edition page. See note below.
+
+.. method:: ModelAdmin.changelist_view(self, request, extra_context=None)
+
+Django view for the model instances change list/actions page. See note below.
+
+.. method:: ModelAdmin.delete_view(self, request, object_id, extra_context=None)
+
+Django view for the model instance(s) deletion confirmation page. See note below.
+
+.. method:: ModelAdmin.history_view(self, request, object_id, extra_context=None)
+
+Django view for the page that shows the modification history for a given model
+instance.
+
+Unlike the hook-type ``ModelAdmin`` methods detailed in the previous section,
+these five methods are in reality designed to be invoked as Django views from
+the admin application URL dispatching handler to render the pages that deal
+with model instances CRUD operations. As a result, completely overriding these
+methods will significantly change the behavior of the admin application.
+
+One common reason for overriding these methods is to augment the context data
+that is provided to the template that renders the view. In the following
+example, the change view is overridden so that the rendered template is
+provided some extra mapping data that would not otherwise be available::
+
+    class MyModelAdmin(admin.ModelAdmin):
+
+        # A template for a very customized change view:
+        change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html'
+
+        def get_osm_info(self):
+            # ...
+
+        def change_view(self, request, object_id, extra_context=None):
+            my_context = {
+                'osm_data': self.get_osm_info(),
+            }
+            return super(MyModelAdmin, self).change_view(request, object_id,
+                extra_context=my_context)
+
+``ModelAdmin`` media definitions
+--------------------------------
+
+There are times where you would like add a bit of CSS and/or JavaScript to
+the add/change views. This can be accomplished by using a Media inner class
+on your ``ModelAdmin``::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        class Media:
+            css = {
+                "all": ("my_styles.css",)
+            }
+            js = ("my_code.js",)
+
+Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
+apply as :doc:`regular media definitions on forms </topics/forms/media>`.
+
+Django admin Javascript makes use of the `jQuery`_ library. To avoid
+conflict with user scripts, Django's jQuery is namespaced as
+``django.jQuery``. If you want to use jQuery in your own admin
+JavaScript without including a second copy, you can use the
+``django.jQuery`` object on changelist and add/edit views.
+
+.. _jQuery: http://jquery.com
+
+Adding custom validation to the admin
+-------------------------------------
+
+Adding custom validation of data in the admin is quite easy. The automatic admin
+interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you
+the ability define your own form::
+
+    class ArticleAdmin(admin.ModelAdmin):
+        form = MyArticleAdminForm
+
+``MyArticleAdminForm`` can be defined anywhere as long as you import where
+needed. Now within your form you can add your own custom validation for
+any field::
+
+    class MyArticleAdminForm(forms.ModelForm):
+        class Meta:
+            model = Article
+
+        def clean_name(self):
+            # do something that validates your data
+            return self.cleaned_data["name"]
+
+It is important you use a ``ModelForm`` here otherwise things can break. See the
+:doc:`forms </ref/forms/index>` documentation on :doc:`custom validation
+</ref/forms/validation>` and, more specifically, the
+:ref:`model form validation notes <overriding-modelform-clean-method>` for more
+information.
+
+.. _admin-inlines:
+
+``InlineModelAdmin`` objects
+============================
+
+.. class:: InlineModelAdmin
+
+The admin interface has the ability to edit models on the same page as a
+parent model. These are called inlines. Suppose you have these two models::
+
+     class Author(models.Model):
+        name = models.CharField(max_length=100)
+
+     class Book(models.Model):
+        author = models.ForeignKey(Author)
+        title = models.CharField(max_length=100)
+
+You can edit the books authored by an author on the author page. You add
+inlines to a model by specifying them in a ``ModelAdmin.inlines``::
+
+    class BookInline(admin.TabularInline):
+        model = Book
+
+    class AuthorAdmin(admin.ModelAdmin):
+        inlines = [
+            BookInline,
+        ]
+
+Django provides two subclasses of ``InlineModelAdmin`` and they are:
+
+    * ``TabularInline``
+    * ``StackedInline``
+
+The difference between these two is merely the template used to render them.
+
+``InlineModelAdmin`` options
+-----------------------------
+
+The ``InlineModelAdmin`` class is a subclass of ``ModelAdmin`` so it inherits
+all the same functionality as well as some of its own:
+
+.. attribute:: InlineModelAdmin.model
+
+    The model in which the inline is using. This is required.
+
+.. attribute:: InlineModelAdmin.fk_name
+
+    The name of the foreign key on the model. In most cases this will be dealt
+    with automatically, but ``fk_name`` must be specified explicitly if there
+    are more than one foreign key to the same parent model.
+
+.. attribute:: InlineModelAdmin.formset
+
+    This defaults to ``BaseInlineFormSet``. Using your own formset can give you
+    many possibilities of customization. Inlines are built around
+    :ref:`model formsets <model-formsets>`.
+
+.. attribute:: InlineModelAdmin.form
+
+    The value for ``form`` defaults to ``ModelForm``. This is what is passed
+    through to ``inlineformset_factory`` when creating the formset for this
+    inline.
+
+.. _ref-contrib-admin-inline-extra:
+
+.. attribute:: InlineModelAdmin.extra
+
+
+    This controls the number of extra forms the formset will display in addition
+    to the initial forms. See the
+    :doc:`formsets documentation </topics/forms/formsets>` for more information.
+
+    .. versionadded:: 1.2
+
+    For users with JavaScript-enabled browsers, an "Add another" link is
+    provided to enable any number of additional inlines to be added in addition
+    to those provided as a result of the ``extra`` argument.
+
+    The dynamic link will not appear if the number of currently displayed forms
+    exceeds ``max_num``, or if the user does not have JavaScript enabled.
+
+.. _ref-contrib-admin-inline-max-num:
+
+.. attribute:: InlineModelAdmin.max_num
+
+    This controls the maximum number of forms to show in the inline. This
+    doesn't directly correlate to the number of objects, but can if the value
+    is small enough. See :ref:`model-formsets-max-num` for more information.
+
+.. attribute:: InlineModelAdmin.raw_id_fields
+
+    By default, Django's admin uses a select-box interface (<select>) for
+    fields that are ``ForeignKey``. Sometimes you don't want to incur the
+    overhead of having to select all the related instances to display in the
+    drop-down.
+
+    ``raw_id_fields`` is a list of fields you would like to change into a
+    ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``::
+
+        class BookInline(admin.TabularInline):
+            model = Book
+            raw_id_fields = ("pages",)
+
+
+.. attribute:: InlineModelAdmin.template
+
+    The template used to render the inline on the page.
+
+.. attribute:: InlineModelAdmin.verbose_name
+
+    An override to the ``verbose_name`` found in the model's inner ``Meta``
+    class.
+
+.. attribute:: InlineModelAdmin.verbose_name_plural
+
+    An override to the ``verbose_name_plural`` found in the model's inner
+    ``Meta`` class.
+
+.. attribute:: InlineModelAdmin.can_delete
+
+    Specifies whether or not inline objects can be deleted in the inline.
+    Defaults to ``True``.
+
+
+Working with a model with two or more foreign keys to the same parent model
+---------------------------------------------------------------------------
+
+It is sometimes possible to have more than one foreign key to the same model.
+Take this model for instance::
+
+    class Friendship(models.Model):
+        to_person = models.ForeignKey(Person, related_name="friends")
+        from_person = models.ForeignKey(Person, related_name="from_friends")
+
+If you wanted to display an inline on the ``Person`` admin add/change pages
+you need to explicitly define the foreign key since it is unable to do so
+automatically::
+
+    class FriendshipInline(admin.TabularInline):
+        model = Friendship
+        fk_name = "to_person"
+
+    class PersonAdmin(admin.ModelAdmin):
+        inlines = [
+            FriendshipInline,
+        ]
+
+Working with Many-to-Many Models
+--------------------------------
+
+.. versionadded:: 1.2
+
+By default, admin widgets for many-to-many relations will be displayed
+on whichever model contains the actual reference to the ``ManyToManyField``.
+Depending on your ``ModelAdmin`` definition, each many-to-many field in your
+model will be represented by a standard HTML ``<select multiple>``, a
+horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is
+also possible to to replace these widgets with inlines.
+
+Suppose we have the following models::
+
+    class Person(models.Model):
+        name = models.CharField(max_length=128)
+
+    class Group(models.Model):
+        name = models.CharField(max_length=128)
+        members = models.ManyToManyField(Person, related_name='groups')
+
+If you want to display many-to-many relations using an inline, you can do
+so by defining an ``InlineModelAdmin`` object for the relationship::
+
+    class MembershipInline(admin.TabularInline):
+        model = Group.members.through
+
+    class PersonAdmin(admin.ModelAdmin):
+        inlines = [
+            MembershipInline,
+        ]
+
+    class GroupAdmin(admin.ModelAdmin):
+        inlines = [
+            MembershipInline,
+        ]
+        exclude = ('members',)
+
+There are two features worth noting in this example.
+
+Firstly - the ``MembershipInline`` class references ``Group.members.through``.
+The ``through`` attribute is a reference to the model that manages the
+many-to-many relation. This model is automatically created by Django when you
+define a many-to-many field.
+
+Secondly, the ``GroupAdmin`` must manually exclude the ``members`` field.
+Django displays an admin widget for a many-to-many field on the model that
+defines the relation (in this case, ``Group``). If you want to use an inline
+model to represent the many-to-many relationship, you must tell Django's admin
+to *not* display this widget - otherwise you will end up with two widgets on
+your admin page for managing the relation.
+
+In all other respects, the ``InlineModelAdmin`` is exactly the same as any
+other. You can customize the appearance using any of the normal
+``ModelAdmin`` properties.
+
+Working with Many-to-Many Intermediary Models
+----------------------------------------------
+
+When you specify an intermediary model using the ``through`` argument to a
+``ManyToManyField``, the admin will not display a widget by default. This is
+because each instance of that intermediary model requires more information
+than could be displayed in a single widget, and the layout required for
+multiple widgets will vary depending on the intermediate model.
+
+However, we still want to be able to edit that information inline. Fortunately,
+this is easy to do with inline admin models. Suppose we have the following
+models::
+
+    class Person(models.Model):
+        name = models.CharField(max_length=128)
+
+    class Group(models.Model):
+        name = models.CharField(max_length=128)
+        members = models.ManyToManyField(Person, through='Membership')
+
+    class Membership(models.Model):
+        person = models.ForeignKey(Person)
+        group = models.ForeignKey(Group)
+        date_joined = models.DateField()
+        invite_reason = models.CharField(max_length=64)
+
+The first step in displaying this intermediate model in the admin is to
+define an inline class for the ``Membership`` model::
+
+    class MembershipInline(admin.TabularInline):
+        model = Membership
+        extra = 1
+
+This simple example uses the default ``InlineModelAdmin`` values for the
+``Membership`` model, and limits the extra add forms to one. This could be
+customized using any of the options available to ``InlineModelAdmin`` classes.
+
+Now create admin views for the ``Person`` and ``Group`` models::
+
+    class PersonAdmin(admin.ModelAdmin):
+        inlines = (MembershipInline,)
+
+    class GroupAdmin(admin.ModelAdmin):
+        inlines = (MembershipInline,)
+
+Finally, register your ``Person`` and ``Group`` models with the admin site::
+
+    admin.site.register(Person, PersonAdmin)
+    admin.site.register(Group, GroupAdmin)
+
+Now your admin site is set up to edit ``Membership`` objects inline from
+either the ``Person`` or the ``Group`` detail pages.
+
+Using generic relations as an inline
+------------------------------------
+
+It is possible to use an inline with generically related objects. Let's say
+you have the following models::
+
+    class Image(models.Model):
+        image = models.ImageField(upload_to="images")
+        content_type = models.ForeignKey(ContentType)
+        object_id = models.PositiveIntegerField()
+        content_object = generic.GenericForeignKey("content_type", "object_id")
+
+    class Product(models.Model):
+        name = models.CharField(max_length=100)
+
+If you want to allow editing and creating ``Image`` instance on the ``Product``
+add/change views you can simply use ``GenericInlineModelAdmin`` provided by
+``django.contrib.contenttypes.generic``. In your ``admin.py`` for this
+example app::
+
+    from django.contrib import admin
+    from django.contrib.contenttypes import generic
+
+    from myproject.myapp.models import Image, Product
+
+    class ImageInline(generic.GenericTabularInline):
+        model = Image
+
+    class ProductAdmin(admin.ModelAdmin):
+        inlines = [
+            ImageInline,
+        ]
+
+    admin.site.register(Product, ProductAdmin)
+
+``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
+and ``GenericStackedInline`` and behave just like any other inline. See the
+:doc:`contenttypes documentation </ref/contrib/contenttypes>` for more specific
+information.
+
+Overriding Admin Templates
+==========================
+
+It is relatively easy to override many of the templates which the admin module
+uses to generate the various pages of an admin site. You can even override a few
+of these templates for a specific app, or a specific model.
+
+Set up your projects admin template directories
+-----------------------------------------------
+
+The admin template files are located in the ``contrib/admin/templates/admin``
+directory.
+
+In order to override one or more of them, first create an ``admin`` directory in
+your project's ``templates`` directory. This can be any of the directories you
+specified in ``TEMPLATE_DIRS``.
+
+Within this ``admin`` directory, create sub-directories named after your app.
+Within these app subdirectories create sub-directories named after your models.
+Note, that the admin app will lowercase the model name when looking for the
+directory, so make sure you name the directory in all lowercase if you are going
+to run your app on a case-sensitive filesystem.
+
+To override an admin template for a specific app, copy and edit the template
+from the ``django/contrib/admin/templates/admin`` directory, and save it to one
+of the directories you just created.
+
+For example, if we wanted to add a tool to the change list view for all the
+models in an app named ``my_app``, we would copy
+``contrib/admin/templates/admin/change_list.html`` to the
+``templates/admin/my_app/`` directory of our project, and make any necessary
+changes.
+
+If we wanted to add a tool to the change list view for only a specific model
+named 'Page', we would copy that same file to the
+``templates/admin/my_app/page`` directory of our project.
+
+Overriding vs. replacing an admin template
+------------------------------------------
+
+Because of the modular design of the admin templates, it is usually neither
+necessary nor advisable to replace an entire template. It is almost always
+better to override only the section of the template which you need to change.
+
+To continue the example above, we want to add a new link next to the ``History``
+tool for the ``Page`` model. After looking at ``change_form.html`` we determine
+that we only need to override the ``object-tools`` block. Therefore here is our
+new ``change_form.html`` :
+
+.. code-block:: html+django
+
+    {% extends "admin/change_form.html" %}
+    {% load i18n %}
+    {% block object-tools %}
+    {% if change %}{% if not is_popup %}
+      <ul class="object-tools">
+        <li><a href="history/" class="historylink">{% trans "History" %}</a></li>
+        <li><a href="mylink/" class="historylink">My Link</a></li>
+        {% if has_absolute_url %}
+            <li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink">
+                {% trans "View on site" %}</a>
+            </li>
+        {% endif%}
+      </ul>
+    {% endif %}{% endif %}
+    {% endblock %}
+
+And that's it! If we placed this file in the ``templates/admin/my_app``
+directory, our link would appear on every model's change form.
+
+Templates which may be overridden per app or model
+--------------------------------------------------
+
+Not every template in ``contrib/admin/templates/admin`` may be overridden per
+app or per model. The following can:
+
+    * ``app_index.html``
+    * ``change_form.html``
+    * ``change_list.html``
+    * ``delete_confirmation.html``
+    * ``object_history.html``
+
+For those templates that cannot be overridden in this way, you may still
+override them for your entire project. Just place the new version in your
+``templates/admin`` directory. This is particularly useful to create custom 404
+and 500 pages.
+
+.. note::
+
+    Some of the admin templates, such as ``change_list_request.html`` are used
+    to render custom inclusion tags. These may be overridden, but in such cases
+    you are probably better off creating your own version of the tag in question
+    and giving it a different name. That way you can use it selectively.
+
+Root and login templates
+------------------------
+
+If you wish to change the index, login or logout templates, you are better off
+creating your own ``AdminSite`` instance (see below), and changing the
+:attr:`AdminSite.index_template` , :attr:`AdminSite.login_template` or
+:attr:`AdminSite.logout_template` properties.
+
+``AdminSite`` objects
+=====================
+
+.. class:: AdminSite(name=None)
+
+A Django administrative site is represented by an instance of
+``django.contrib.admin.sites.AdminSite``; by default, an instance of
+this class is created as ``django.contrib.admin.site`` and you can
+register your models and ``ModelAdmin`` instances with it.
+
+If you'd like to set up your own administrative site with custom
+behavior, however, you're free to subclass ``AdminSite`` and override
+or add anything you like. Then, simply create an instance of your
+``AdminSite`` subclass (the same way you'd instantiate any other
+Python class), and register your models and ``ModelAdmin`` subclasses
+with it instead of using the default.
+
+.. versionadded:: 1.1
+
+When constructing an instance of an ``AdminSite``, you are able to provide
+a unique instance name using the ``name`` argument to the constructor. This
+instance name is used to identify the instance, especially when
+:ref:`reversing admin URLs <admin-reverse-urls>`. If no instance name is
+provided, a default instance name of ``admin`` will be used.
+
+``AdminSite`` attributes
+------------------------
+
+Templates can override or extend base admin templates as described in
+`Overriding Admin Templates`_.
+
+.. attribute:: AdminSite.index_template
+
+Path to a custom template that will be used by the admin site main index view.
+
+.. attribute:: AdminSite.login_template
+
+Path to a custom template that will be used by the admin site login view.
+
+.. attribute:: AdminSite.logout_template
+
+.. versionadded:: 1.2
+
+Path to a custom template that will be used by the admin site logout view.
+
+.. attribute:: AdminSite.password_change_template
+
+.. versionadded:: 1.2
+
+Path to a custom template that will be used by the admin site password change
+view.
+
+.. attribute:: AdminSite.password_change_done_template
+
+.. versionadded:: 1.2
+
+Path to a custom template that will be used by the admin site password change
+done view.
+
+Hooking ``AdminSite`` instances into your URLconf
+-------------------------------------------------
+
+The last step in setting up the Django admin is to hook your ``AdminSite``
+instance into your URLconf. Do this by pointing a given URL at the
+``AdminSite.urls`` method.
+
+In this example, we register the default ``AdminSite`` instance
+``django.contrib.admin.site`` at the URL ``/admin/`` ::
+
+    # urls.py
+    from django.conf.urls.defaults import *
+    from django.contrib import admin
+
+    admin.autodiscover()
+
+    urlpatterns = patterns('',
+        (r'^admin/', include(admin.site.urls)),
+    )
+
+Above we used ``admin.autodiscover()`` to automatically load the
+``INSTALLED_APPS`` admin.py modules.
+
+In this example, we register the ``AdminSite`` instance
+``myproject.admin.admin_site`` at the URL ``/myadmin/`` ::
+
+    # urls.py
+    from django.conf.urls.defaults import *
+    from myproject.admin import admin_site
+
+    urlpatterns = patterns('',
+        (r'^myadmin/', include(admin_site.urls)),
+    )
+
+There is really no need to use autodiscover when using your own ``AdminSite``
+instance since you will likely be importing all the per-app admin.py modules
+in your ``myproject.admin`` module.
+
+Multiple admin sites in the same URLconf
+----------------------------------------
+
+It's easy to create multiple instances of the admin site on the same
+Django-powered Web site. Just create multiple instances of ``AdminSite`` and
+root each one at a different URL.
+
+.. versionchanged:: 1.1
+    The method for hooking ``AdminSite`` instances into urls has changed in
+    Django 1.1.
+
+In this example, the URLs ``/basic-admin/`` and ``/advanced-admin/`` feature
+separate versions of the admin site -- using the ``AdminSite`` instances
+``myproject.admin.basic_site`` and ``myproject.admin.advanced_site``,
+respectively::
+
+    # urls.py
+    from django.conf.urls.defaults import *
+    from myproject.admin import basic_site, advanced_site
+
+    urlpatterns = patterns('',
+        (r'^basic-admin/', include(basic_site.urls)),
+        (r'^advanced-admin/', include(advanced_site.urls)),
+    )
+
+``AdminSite`` instances take a single argument to their constructor, their
+name, which can be anything you like. This argument becomes the prefix to the
+URL names for the purposes of :ref:`reversing them<admin-reverse-urls>`. This
+is only necessary if you are using more than one ``AdminSite``.
+
+Adding views to admin sites
+---------------------------
+
+.. versionadded:: 1.1
+
+Just like :class:`ModelAdmin`, :class:`AdminSite` provides a
+:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method
+that can be overridden to define additional views for the site. To add
+a new view to your admin site, extend the base
+:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include
+a pattern for your new view.
+
+.. note::
+    Any view you render that uses the admin templates, or extends the base
+    admin template, should provide the ``current_app`` argument to
+    ``RequestContext`` or ``Context`` when rendering the template.  It should
+    be set to either ``self.name`` if your view is on an ``AdminSite`` or
+    ``self.admin_site.name`` if your view is on a ``ModelAdmin``.
+
+.. _admin-reverse-urls:
+
+Reversing Admin URLs
+====================
+
+.. versionadded:: 1.1
+
+When an :class:`AdminSite` is deployed, the views provided by that site are
+accessible using Django's :ref:`URL reversing system <naming-url-patterns>`.
+
+The :class:`AdminSite` provides the following named URL patterns:
+
+    ======================  ========================  =============
+    Page                    URL name                  Parameters
+    ======================  ========================  =============
+    Index                   ``index``
+    Logout                  ``logout``
+    Password change         ``password_change``
+    Password change done    ``password_change_done``
+    i18n javascript         ``jsi18n``
+    Application index page  ``app_list``              ``app_label``
+    ======================  ========================  =============
+
+Each :class:`ModelAdmin` instance provides an additional set of named URLs:
+
+    ======================  ===============================================   =============
+    Page                    URL name                                          Parameters
+    ======================  ===============================================   =============
+    Changelist              ``{{ app_label }}_{{ model_name }}_changelist``
+    Add                     ``{{ app_label }}_{{ model_name }}_add``
+    History                 ``{{ app_label }}_{{ model_name }}_history``      ``object_id``
+    Delete                  ``{{ app_label }}_{{ model_name }}_delete``       ``object_id``
+    Change                  ``{{ app_label }}_{{ model_name }}_change``       ``object_id``
+    ======================  ===============================================   =============
+
+These named URLs are registered with the application namespace ``admin``, and
+with an instance namespace corresponding to the name of the Site instance.
+
+So - if you wanted to get a reference to the Change view for a particular
+``Choice`` object (from the polls application) in the default admin, you would
+call::
+
+    >>> from django.core import urlresolvers
+    >>> c = Choice.objects.get(...)
+    >>> change_url = urlresolvers.reverse('admin:polls_choice_change', args=(c.id,))
+
+This will find the first registered instance of the admin application (whatever the instance
+name), and resolve to the view for changing ``poll.Choice`` instances in that instance.
+
+If you want to find a URL in a specific admin instance, provide the name of that instance
+as a ``current_app`` hint to the reverse call. For example, if you specifically wanted
+the admin view from the admin instance named ``custom``, you would need to call::
+
+    >>> change_url = urlresolvers.reverse('custom:polls_choice_change', args=(c.id,))
+
+For more details, see the documentation on :ref:`reversing namespaced URLs
+<topics-http-reversing-url-namespaces>`.
diff --git a/parts/django/docs/ref/contrib/auth.txt b/parts/django/docs/ref/contrib/auth.txt
new file mode 100644
index 0000000..619b38e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/auth.txt
@@ -0,0 +1,4 @@
+``django.contrib.auth``
+=======================
+
+See :doc:`/topics/auth`.
diff --git a/parts/django/docs/ref/contrib/comments/custom.txt b/parts/django/docs/ref/contrib/comments/custom.txt
new file mode 100644
index 0000000..5411d9c
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/custom.txt
@@ -0,0 +1,202 @@
+==================================
+Customizing the comments framework
+==================================
+
+.. currentmodule:: django.contrib.comments
+
+If the built-in comment framework doesn't quite fit your needs, you can extend
+the comment app's behavior to add custom data and logic. The comments framework
+lets you extend the built-in comment model, the built-in comment form, and the
+various comment views.
+
+The :setting:`COMMENTS_APP` setting is where this customization begins. Set
+:setting:`COMMENTS_APP` to the name of the app you'd like to use to provide
+custom behavior. You'll use the same syntax as you'd use for
+:setting:`INSTALLED_APPS`, and the app given must also be in the
+:setting:`INSTALLED_APPS` list.
+
+For example, if you wanted to use an app named ``my_comment_app``, your
+settings file would contain::
+
+    INSTALLED_APPS = [
+        ...
+        'my_comment_app',
+        ...
+    ]
+
+    COMMENTS_APP = 'my_comment_app'
+
+The app named in :setting:`COMMENTS_APP` provides its custom behavior by
+defining some module-level functions in the app's ``__init__.py``. The
+:ref:`complete list of these functions <custom-comment-app-api>` can be found
+below, but first let's look at a quick example.
+
+An example custom comments app
+==============================
+
+One of the most common types of customization is modifying the set of fields
+provided on the built-in comment model. For example, some sites that allow
+comments want the commentator to provide a title for their comment; the built-in
+comment model has no field for that title.
+
+To make this kind of customization, we'll need to do three things:
+
+    #. Create a custom comment :class:`~django.db.models.Model` that adds on the
+       "title" field.
+
+    #. Create a custom comment :class:`~django.forms.Form` that also adds this
+       "title" field.
+
+    #. Inform Django of these objects by defining a few functions in a
+       custom :setting:`COMMENTS_APP`.
+
+So, carrying on the example above, we're dealing with a typical app structure in
+the ``my_custom_app`` directory::
+
+    my_custom_app/
+        __init__.py
+        models.py
+        forms.py
+
+In the ``models.py`` we'll define a ``CommentWithTitle`` model::
+
+    from django.db import models
+    from django.contrib.comments.models import Comment
+
+    class CommentWithTitle(Comment):
+        title = models.CharField(max_length=300)
+
+Most custom comment models will subclass the :class:`Comment` model. However,
+if you want to substantially remove or change the fields available in the
+:class:`Comment` model, but don't want to rewrite the templates, you could
+try subclassing from :class:`BaseCommentAbstractModel`.
+
+Next, we'll define a custom comment form in ``forms.py``. This is a little more
+tricky: we have to both create a form and override
+:meth:`CommentForm.get_comment_model` and
+:meth:`CommentForm.get_comment_create_data` to return deal with our custom title
+field::
+
+    from django import forms
+    from django.contrib.comments.forms import CommentForm
+    from my_comment_app.models import CommentWithTitle
+
+    class CommentFormWithTitle(CommentForm):
+        title = forms.CharField(max_length=300)
+
+        def get_comment_model(self):
+            # Use our custom comment model instead of the built-in one.
+            return CommentWithTitle
+
+        def get_comment_create_data(self):
+            # Use the data of the superclass, and add in the title field
+            data = super(CommentFormWithTitle, self).get_comment_create_data()
+            data['title'] = self.cleaned_data['title']
+            return data
+
+Django provides a couple of "helper" classes to make writing certain types of
+custom comment forms easier; see :mod:`django.contrib.comments.forms` for
+more.
+
+Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
+point Django at these classes we've created::
+
+    from my_comments_app.models import CommentWithTitle
+    from my_comments_app.forms import CommentFormWithTitle
+
+    def get_model():
+        return CommentWithTitle
+
+    def get_form():
+        return CommentFormWithTitle
+
+
+.. warning::
+
+    Be careful not to create cyclic imports in your custom comments app.
+    If you feel your comment configuration isn't being used as defined --
+    for example, if your comment moderation policy isn't being applied --
+    you may have a cyclic import problem.
+
+    If you are having unexplained problems with comments behavior, check
+    if your custom comments application imports (even indirectly)
+    any module that itself imports Django's comments module.
+
+The above process should take care of most common situations. For more
+advanced usage, there are additional methods you can define. Those are
+explained in the next section.
+
+.. _custom-comment-app-api:
+
+Custom comment app API
+======================
+
+The :mod:`django.contrib.comments` app defines the following methods; any
+custom comment app must define at least one of them. All are optional,
+however.
+
+.. function:: get_model()
+
+    Return the :class:`~django.db.models.Model` class to use for comments. This
+    model should inherit from
+    :class:`django.contrib.comments.models.BaseCommentAbstractModel`, which
+    defines necessary core fields.
+
+    The default implementation returns
+    :class:`django.contrib.comments.models.Comment`.
+
+.. function:: get_form()
+
+    Return the :class:`~django.forms.Form` class you want to use for
+    creating, validating, and saving your comment model.  Your custom
+    comment form should accept an additional first argument,
+    ``target_object``, which is the object the comment will be
+    attached to.
+
+    The default implementation returns
+    :class:`django.contrib.comments.forms.CommentForm`.
+
+    .. note::
+
+        The default comment form also includes a number of unobtrusive
+        spam-prevention features (see
+        :ref:`notes-on-the-comment-form`).  If replacing it with your
+        own form, you may want to look at the source code for the
+        built-in form and consider incorporating similar features.
+
+.. function:: get_form_target()
+
+    Return the URL for POSTing comments. This will be the ``<form action>``
+    attribute when rendering your comment form.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`post_comment` view.
+
+    .. note::
+
+        If you provide a custom comment model and/or form, but you
+        want to use the default :func:`post_comment` view, you will
+        need to be aware that it requires the model and form to have
+        certain additional attributes and methods: see the
+        :func:`post_comment` view documentation for details.
+
+.. function:: get_flag_url()
+
+    Return the URL for the "flag this comment" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.flag` view.
+
+.. function:: get_delete_url()
+
+    Return the URL for the "delete this comment" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.delete` view.
+
+.. function:: get_approve_url()
+
+    Return the URL for the "approve this comment from moderation" view.
+
+    The default implementation returns a reverse-resolved URL pointing
+    to the :func:`django.contrib.comments.views.moderation.approve` view.
diff --git a/parts/django/docs/ref/contrib/comments/example.txt b/parts/django/docs/ref/contrib/comments/example.txt
new file mode 100644
index 0000000..424bdb1
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/example.txt
@@ -0,0 +1,208 @@
+.. highlightlang:: html+django
+
+===========================================
+Example of using the in-built comments app
+===========================================
+
+Follow the first three steps of the quick start guide in the
+:doc:`documentation </ref/contrib/comments/index>`.
+
+Now suppose, you have an app (``blog``) with a model (``Post``)
+to which you want to attach comments. Let us also suppose that
+you have a template called ``blog_detail.html`` where you want
+to display the comments list and comment form.
+
+Template
+========
+
+First, we should load the ``comment`` template tags in the
+``blog_detail.html`` so that we can use it's functionality. So
+just like all other custom template tag libraries::
+
+    {% load comments %}
+
+Next, let us add the number of comments attached to the particular
+model instance of ``Post``. For this we assume that a context
+variable ``object_pk`` is present which gives the ``id`` of the
+instance of ``Post``.
+
+The usage of the :ttag:`get_comment_count` tag is like below::
+
+   {% get_comment_count for blog.post object_pk as comment_count %}
+   <p>{{ comment_count }} comments have been posted.</p>
+
+If you have the instance (say ``entry``) of the model (``Post``)
+available in the context, then you can refer to it directly::
+
+   {% get_comment_count for entry as comment_count %}
+   <p>{{ comment_count }} comments have been posted.</p>
+
+.. versionadded:: 1.2
+
+Next, we can use the :ttag:`render_comment_list` tag, to render all comments
+to the given instance (``entry``) by using the ``comments/list.html`` template.
+
+   {% render_comment_list for entry %}
+
+Django will will look for the ``list.html`` under the following directories
+(for our example)::
+
+  comments/blog/post/list.html
+  comments/blog/list.html
+  comments/list.html
+
+To get a list of comments, we make use of the :ttag:`get_comment_list` tag.
+This tag's usage is very similar to the :ttag:`get_comment_count` tag. We
+need to remember that the :ttag:`get_comment_list` returns a list of comments
+and hence we will have to iterate through them to display them::
+
+   {% get_comment_list for blog.post object_pk as comment_list %}
+   {% for comment in comment_list %}
+   <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p>
+   ...
+   <p>Comment: {{ comment.comment }}</p>
+   ...
+   {% endfor %}
+
+Finally, we display the comment form, enabling users to enter their
+comments. There are two ways of doing so. The first is when you want to
+display the comments template available under your ``comments/form.html``.
+The other method gives you a chance to customize the form.
+
+The first method makes use of the :ttag:`render_comment_form` tag. It's usage
+too is similar to the other three tags we have discussed above::
+
+   {% render_comment_form for entry %}
+
+It looks for the ``form.html`` under the following directories
+(for our example)::
+
+   comments/blog/post/form.html
+   comments/blog/form.html
+   comments/form.html
+
+Since we customize the form in the second method, we make use of another
+tag called :ttag:`comment_form_target`. This tag on rendering gives the URL
+where the comment form is posted. Without any :doc:`customization
+</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to
+``/comments/post/``. We use this tag in the form's ``action`` attribute.
+
+The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by
+creating a context variable. One can iterate over the ``form`` object to
+get individual fields. This gives you fine-grain control over the form::
+
+  {% for field in form %}
+  {% ifequal field.name "comment" %}
+    <!-- Customize the "comment" field, say, make CSS changes -->
+  ...
+  {% endfor %}
+
+But let's look at a simple example::
+
+  {% get_comment_form for entry as form %}
+  <!-- A context variable called form is created with the necessary hidden
+  fields, timestamps and security hashes -->
+  <table>
+  <form action="{% comment_form_target %}" method="post">
+    {{ form }}
+    <tr>
+      <td></td>
+      <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
+    </tr>
+  </form>
+  </table>
+
+Flagging
+========
+
+If you want your users to be able to flag comments (say for profanity), you
+can just direct them (by placing a link in your comment list) to ``/flag/{{
+comment.id }}/``. Similarly, a user with requisite permissions (``"Can
+moderate comments"``) can approve and delete comments. This can also be
+done through the ``admin`` as you'll see later. You might also want to
+customize the following templates:
+
+  * ``flag.html``
+  * ``flagged.html``
+  * ``approve.html``
+  * ``approved.html``
+  * ``delete.html``
+  * ``deleted.html``
+
+found under the directory structure we saw for ``form.html``.
+
+Feeds
+=====
+
+Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the
+latest comments, you can use the in-built :class:`LatestCommentFeed`. Just
+enable it in your project's ``urls.py``:
+
+.. code-block:: python
+
+  from django.conf.urls.defaults import *
+  from django.contrib.comments.feeds import LatestCommentFeed
+
+  feeds = {
+      'latest': LatestCommentFeed,
+  }
+
+  urlpatterns = patterns('',
+  # ...
+      (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+          {'feed_dict': feeds}),
+  # ...
+  )
+
+Now you should have the latest comment feeds being served off ``/feeds/latest/``.
+
+Moderation
+==========
+
+Now that we have the comments framework working, we might want to have some
+moderation setup to administer the comments. The comments framework comes
+in-built with :doc:`generic comment moderation
+</ref/contrib/comments/moderation>`. The comment moderation has the following
+features (all of which or only certain can be enabled):
+
+  * Enable comments for a particular model instance.
+  * Close comments after a particular (user-defined) number of days.
+  * Email new comments to the site-staff.
+
+To enable comment moderation, we subclass the :class:`CommentModerator` and
+register it with the moderation features we want. Let us suppose we want to
+close comments after 7 days of posting and also send out an email to the
+site staff. In ``blog/models.py``, we register a comment moderator in the
+following way:
+
+.. code-block:: python
+
+   from django.contrib.comments.moderation import CommentModerator, moderator
+   from django.db import models
+
+   class Post(models.Model):
+       title   = models.CharField(max_length = 255)
+       content = models.TextField()
+       posted_date = models.DateTimeField()
+
+   class PostModerator(CommentModerator):
+       email_notification = True
+       auto_close_field   = 'posted_date'
+       # Close the comments after 7 days.
+       close_after        = 7
+
+   moderator.register(Post, PostModerator)
+
+The generic comment moderation also has the facility to remove comments.
+These comments can then be moderated by any user who has access to the
+``admin`` site and the ``Can moderate comments`` permission (can be set
+under the ``Users`` page in the ``admin``).
+
+The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the
+``Action`` drop-down in the ``admin`` under the ``Comments`` page.
+
+.. note::
+
+     Only a super-user will be able to delete comments from the database.
+     ``Remove Comments`` only sets the ``is_public`` attribute to
+     ``False``.
diff --git a/parts/django/docs/ref/contrib/comments/forms.txt b/parts/django/docs/ref/contrib/comments/forms.txt
new file mode 100644
index 0000000..c21a27b
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/forms.txt
@@ -0,0 +1,46 @@
+====================
+Comment form classes
+====================
+
+.. module:: django.contrib.comments.forms
+   :synopsis: Forms for dealing with the built-in comment model.
+
+The ``django.contrib.comments.forms`` module contains a handful of forms
+you'll use when writing custom views dealing with comments, or when writing
+:doc:`custom comment apps </ref/contrib/comments/custom>`.
+
+.. class:: CommentForm
+
+   The main comment form representing the standard, built-in way of handling
+   submitted comments. This is the class used by all the views
+   :mod:`django.contrib.comments` to handle submitted comments.
+
+   If you want to build custom views that are similar to Django's built-in
+   comment handling views, you'll probably want to use this form.
+
+Abstract comment forms for custom comment apps
+----------------------------------------------
+
+If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`,
+you might want to replace *some* of the form logic but still rely on parts of
+the existing form.
+
+:class:`CommentForm` is actually composed of a couple of abstract base class
+forms that you can subclass to reuse pieces of the form handling logic:
+
+.. class:: CommentSecurityForm
+
+   Handles the anti-spoofing protection aspects of the comment form handling.
+
+   This class contains the ``content_type`` and ``object_pk`` fields pointing
+   to the object the comment is attached to, along with a ``timestamp`` and a
+   ``security_hash`` of all the form data. Together, the timestamp and the
+   security hash ensure that spammers can't "replay" form submissions and
+   flood you with comments.
+
+.. class:: CommentDetailsForm
+
+   Handles the details of the comment itself.
+
+   This class contains the ``name``, ``email``, ``url``, and the ``comment``
+   field itself, along with the associated validation logic.
\ No newline at end of file
diff --git a/parts/django/docs/ref/contrib/comments/index.txt b/parts/django/docs/ref/contrib/comments/index.txt
new file mode 100644
index 0000000..817871e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/index.txt
@@ -0,0 +1,302 @@
+===========================
+Django's comments framework
+===========================
+
+.. module:: django.contrib.comments
+   :synopsis: Django's comment framework
+
+.. highlightlang:: html+django
+
+Django includes a simple, yet customizable comments framework. The built-in
+comments framework can be used to attach comments to any model, so you can use
+it for comments on blog entries, photos, book chapters, or anything else.
+
+.. note::
+
+    If you used to use Django's older (undocumented) comments framework, you'll
+    need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>`
+    for instructions.
+
+Quick start guide
+=================
+
+To get started using the ``comments`` app, follow these steps:
+
+    #. Install the comments framework by adding ``'django.contrib.comments'`` to
+       :setting:`INSTALLED_APPS`.
+
+    #. Run ``manage.py syncdb`` so that Django will create the comment tables.
+
+    #. Add the comment app's URLs to your project's ``urls.py``:
+
+       .. code-block:: python
+
+            urlpatterns = patterns('',
+                ...
+                (r'^comments/', include('django.contrib.comments.urls')),
+                ...
+            )
+
+    #. Use the `comment template tags`_ below to embed comments in your
+       templates.
+
+You might also want to examine :doc:`/ref/contrib/comments/settings`.
+
+Comment template tags
+=====================
+
+You'll primarily interact with the comment system through a series of template
+tags that let you embed comments and generate forms for your users to post them.
+
+Like all custom template tag libraries, you'll need to :ref:`load the custom
+tags <loading-custom-template-libraries>` before you can use them::
+
+    {% load comments %}
+
+Once loaded you can use the template tags below.
+
+Specifying which object comments are attached to
+------------------------------------------------
+
+Django's comments are all "attached" to some parent object. This can be any
+instance of a Django model. Each of the tags below gives you a couple of
+different ways you can specify which object to attach to:
+
+    #. Refer to the object directly -- the more common method. Most of the
+       time, you'll have some object in the template's context you want
+       to attach the comment to; you can simply use that object.
+
+       For example, in a blog entry page that has a variable named ``entry``,
+       you could use the following to load the number of comments::
+
+            {% get_comment_count for entry as comment_count %}.
+
+    #. Refer to the object by content-type and object id. You'd use this method
+       if you, for some reason, don't actually have direct access to the object.
+
+       Following the above example, if you knew the object ID was ``14`` but
+       didn't have access to the actual object, you could do something like::
+
+            {% get_comment_count for blog.entry 14 as comment_count %}
+
+       In the above, ``blog.entry`` is the app label and (lower-cased) model
+       name of the model class.
+
+Displaying comments
+-------------------
+
+To display a list of comments, you can use the template tags
+:ttag:`render_comment_list` or :ttag:`get_comment_list`.
+
+.. templatetag:: render_comment_list
+
+Quickly rendering a comment list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way to display a list of comments for some object is by using
+:ttag:`render_comment_list`::
+
+    {% render_comment_list for [object] %}
+
+For example::
+
+    {% render_comment_list for event %}
+
+This will render comments using a template named ``comments/list.html``, a
+default version of which is included with Django.
+
+.. templatetag:: get_comment_list
+
+Rendering a custom comment list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get the list of comments for some object, use :ttag:`get_comment_list`::
+
+    {% get_comment_list for [object] as [varname] %}
+
+For example::
+
+    {% get_comment_list for event as comment_list %}
+    {% for comment in comment_list %}
+        ...
+    {% endfor %}
+
+This returns a list of :class:`~django.contrib.comments.models.Comment` objects;
+see :doc:`the comment model documentation </ref/contrib/comments/models>` for
+details.
+
+.. templatetag:: get_comment_permalink
+
+Linking to comments
+-------------------
+
+.. versionadded:: 1.2
+
+To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`::
+
+    {% get_comment_permalink comment_obj [format_string] %}
+
+By default, the named anchor that will be appended to the URL will be the letter
+'c' followed by the comment id, for example 'c82'. You may specify a custom
+format string if you wish to override this behavior::
+
+    {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%}
+
+The format string is a standard python format string. Valid mapping keys
+include any attributes of the comment object.
+
+Regardless of whether you specify a custom anchor pattern, you must supply a
+matching named anchor at a suitable place in your template.
+
+For example::
+
+    {% for comment in comment_list %}
+        <a name="c{{ comment.id }}"></a>
+        <a href="{% get_comment_permalink comment %}">
+            permalink for comment #{{ forloop.counter }}
+        </a>
+        ...
+    {% endfor %}
+
+.. warning::
+
+    There's a known bug in Safari/Webkit which causes the named anchor to be
+    forgotten following a redirect. The practical impact for comments is that
+    the Safari/webkit browsers will arrive at the correct page but will not
+    scroll to the named anchor.
+
+.. templatetag:: get_comment_count
+
+Counting comments
+-----------------
+
+To count comments attached to an object, use :ttag:`get_comment_count`::
+
+    {% get_comment_count for [object] as [varname]  %}
+
+For example::
+
+        {% get_comment_count for event as comment_count %}
+
+        <p>This event has {{ comment_count }} comments.</p>
+
+
+Displaying the comment post form
+--------------------------------
+
+To show the form that users will use to post a comment, you can use
+:ttag:`render_comment_form` or :ttag:`get_comment_form`
+
+.. templatetag:: render_comment_form
+
+Quickly rendering the comment form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way to display a comment form is by using
+:ttag:`render_comment_form`::
+
+    {% render_comment_form for [object] %}
+
+For example::
+
+    {% render_comment_form for event %}
+
+This will render comments using a template named ``comments/form.html``, a
+default version of which is included with Django.
+
+.. templatetag:: get_comment_form
+
+Rendering a custom comment form
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want more control over the look and feel of the comment form, you use use
+:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that
+you can use in the template::
+
+    {% get_comment_form for [object] as [varname] %}
+
+A complete form might look like::
+
+    {% get_comment_form for event as form %}
+    <form action="{% comment_form_target %}" method="post">
+      {{ form }}
+      <tr>
+        <td></td>
+        <td><input type="submit" name="preview" class="submit-post" value="Preview"></td>
+      </tr>
+    </form>
+
+Be sure to read the `notes on the comment form`_, below, for some special
+considerations you'll need to make if you're using this approach.
+
+.. templatetag:: comment_form_target
+
+Getting the comment form target
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may have noticed that the above example uses another template tag --
+:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the
+form. This will always return the correct URL that comments should be posted to;
+you'll always want to use it like above::
+
+    <form action="{% comment_form_target %}" method="post">
+
+Redirecting after the comment post
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To specify the URL you want to redirect to after the comment has been posted,
+you can include a hidden form input called ``next`` in your comment form. For example::
+
+    <input type="hidden" name="next" value="{% url my_comment_was_posted %}" />
+
+.. _notes-on-the-comment-form:
+
+Notes on the comment form
+-------------------------
+
+The form used by the comment system has a few important anti-spam attributes you
+should know about:
+
+    * It contains a number of hidden fields that contain timestamps, information
+      about the object the comment should be attached to, and a "security hash"
+      used to validate this information. If someone tampers with this data --
+      something comment spammers will try -- the comment submission will fail.
+
+      If you're rendering a custom comment form, you'll need to make sure to
+      pass these values through unchanged.
+
+    * The timestamp is used to ensure that "reply attacks" can't continue very
+      long. Users who wait too long between requesting the form and posting a
+      comment will have their submissions refused.
+
+    * The comment form includes a "honeypot_" field. It's a trap: if any data is
+      entered in that field, the comment will be considered spam (spammers often
+      automatically fill in all fields in an attempt to make valid submissions).
+
+      The default form hides this field with a piece of CSS and further labels
+      it with a warning field; if you use the comment form with a custom
+      template you should be sure to do the same.
+
+The comments app also depends on the more general :doc:`Cross Site Request
+Forgery protection </ref/contrib/csrf>` that comes with Django.  As described in
+the documentation, it is best to use ``CsrfViewMiddleware``.  However, if you
+are not using that, you will need to use the ``csrf_protect`` decorator on any
+views that include the comment form, in order for those views to be able to
+output the CSRF token and cookie.
+
+.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing)
+
+More information
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   models
+   settings
+   signals
+   upgrade
+   custom
+   forms
+   moderation
+   example
diff --git a/parts/django/docs/ref/contrib/comments/models.txt b/parts/django/docs/ref/contrib/comments/models.txt
new file mode 100644
index 0000000..e773790
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/models.txt
@@ -0,0 +1,80 @@
+===========================
+The built-in comment models
+===========================
+
+.. module:: django.contrib.comments.models
+   :synopsis: The built-in comment models
+
+.. class:: Comment
+
+    Django's built-in comment model. Has the following fields:
+
+    .. attribute:: content_object
+
+        A :class:`~django.contrib.contettypes.generic.GenericForeignKey`
+        attribute pointing to the object the comment is attached to. You can use
+        this to get at the related object (i.e. ``my_comment.content_object``).
+
+        Since this field is a
+        :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's
+        actually syntactic sugar on top of two underlying attributes, described
+        below.
+
+    .. attribute:: content_type
+
+        A :class:`~django.db.models.ForeignKey` to
+        :class:`~django.contrib.contenttypes.models.ContentType`; this is the
+        type of the object the comment is attached to.
+
+    .. attribute:: object_pk
+
+        A :class:`~django.db.models.TextField` containing the primary
+        key of the object the comment is attached to.
+
+    .. attribute:: site
+
+        A :class:`~django.db.models.ForeignKey` to the
+        :class:`~django.contrib.sites.models.Site` on which the comment was
+        posted.
+
+    .. attribute:: user
+
+        A :class:`~django.db.models.ForeignKey` to the
+        :class:`~django.contrib.auth.models.User` who posted the comment.
+        May be blank if the comment was posted by an unauthenticated user.
+
+    .. attribute:: user_name
+
+        The name of the user who posted the comment.
+
+    .. attribute:: user_email
+
+        The email of the user who posted the comment.
+
+    .. attribute:: user_url
+
+        The URL entered by the person who posted the comment.
+
+    .. attribute:: comment
+
+        The actual content of the comment itself.
+
+    .. attribute:: submit_date
+
+        The date the comment was submitted.
+
+    .. attribute:: ip_address
+
+        The IP address of the user posting the comment.
+
+    .. attribute:: is_public
+
+        ``False`` if the comment is in moderation (see
+        :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will
+        be displayed on the site.
+
+    .. attribute:: is_removed
+
+        ``True`` if the comment was removed. Used to keep track of removed
+        comments instead of just deleting them.
+
diff --git a/parts/django/docs/ref/contrib/comments/moderation.txt b/parts/django/docs/ref/contrib/comments/moderation.txt
new file mode 100644
index 0000000..519bc5e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/moderation.txt
@@ -0,0 +1,230 @@
+==========================
+Generic comment moderation
+==========================
+
+.. module:: django.contrib.comments.moderation
+   :synopsis: Support for automatic comment moderation.
+
+Django's bundled comments application is extremely useful on its own,
+but the amount of comment spam circulating on the Web today
+essentially makes it necessary to have some sort of automatic
+moderation system in place for any application which makes use of
+comments. To make this easier to handle in a consistent fashion,
+``django.contrib.comments.moderation`` provides a generic, extensible
+comment-moderation system which can be applied to any model or set of
+models which want to make use of Django's comment system.
+
+
+Overview
+========
+
+The entire system is contained within ``django.contrib.comments.moderation``,
+and uses a two-step process to enable moderation for any given model:
+
+1. A subclass of :class:`CommentModerator`
+   is defined which specifies the moderation options the model wants to
+   enable.
+
+2. The model is registered with the moderation system, passing in the
+   model class and the class which specifies its moderation options.
+
+A simple example is the best illustration of this. Suppose we have the
+following model, which would represent entries in a Weblog::
+
+    from django.db import models
+    
+    class Entry(models.Model):
+        title = models.CharField(maxlength=250)
+        body = models.TextField()
+        pub_date = models.DateTimeField()
+        enable_comments = models.BooleanField()
+
+Now, suppose that we want the following steps to be applied whenever a
+new comment is posted on an ``Entry``:
+
+1. If the ``Entry``'s ``enable_comments`` field is ``False``, the
+   comment will simply be disallowed (i.e., immediately deleted).
+
+2. If the ``enable_comments`` field is ``True``, the comment will be
+   allowed to save.
+
+3. Once the comment is saved, an email should be sent to site staff
+   notifying them of the new comment.
+
+Accomplishing this is fairly straightforward and requires very little
+code::
+
+    from django.contrib.comments.moderation import CommentModerator, moderator
+    
+    class EntryModerator(CommentModerator):
+        email_notification = True
+        enable_field = 'enable_comments'
+    
+    moderator.register(Entry, EntryModerator)
+
+The :class:`CommentModerator` class pre-defines a number of useful moderation
+options which subclasses can enable or disable as desired, and ``moderator``
+knows how to work with them to determine whether to allow a comment, whether
+to moderate a comment which will be allowed to post, and whether to email
+notifications of new comments.
+
+Built-in moderation options
+---------------------------
+
+.. class:: CommentModerator
+
+    Most common comment-moderation needs can be handled by subclassing
+    :class:`CommentModerator` and
+    changing the values of pre-defined attributes; the full range of built-in
+    options is as follows.
+
+    .. attribute:: auto_close_field
+
+        If this is set to the name of a
+        :class:`~django.db.models.fields.DateField` or
+        :class:`~django.db.models.fields.DateTimeField` on the model for which
+        comments are being moderated, new comments for objects of that model
+        will be disallowed (immediately deleted) when a certain number of days
+        have passed after the date specified in that field. Must be
+        used in conjunction with :attr:`close_after`, which specifies the
+        number of days past which comments should be
+        disallowed. Default value is ``None``.
+
+    .. attribute:: auto_moderate_field
+
+        Like :attr:`auto_close_field`, but instead of outright deleting
+        new comments when the requisite number of days have elapsed,
+        it will simply set the ``is_public`` field of new comments to
+        ``False`` before saving them. Must be used in conjunction with
+        :attr:`moderate_after`, which specifies the number of days past
+        which comments should be moderated. Default value is ``None``.
+
+    .. attribute:: close_after
+
+        If :attr:`auto_close_field` is used, this must specify the number
+        of days past the value of the field specified by
+        :attr:`auto_close_field` after which new comments for an object
+        should be disallowed. Default value is ``None``.
+
+    .. attribute:: email_notification
+
+        If ``True``, any new comment on an object of this model which
+        survives moderation (i.e., is not deleted) will generate an
+        email to site staff. Default value is ``False``.
+
+    .. attribute:: enable_field
+
+        If this is set to the name of a
+        :class:`~django.db.models.fields.BooleanField` on the model
+        for which comments are being moderated, new comments on
+        objects of that model will be disallowed (immediately deleted)
+        whenever the value of that field is ``False`` on the object
+        the comment would be attached to. Default value is ``None``.
+
+    .. attribute:: moderate_after
+
+        If :attr:`auto_moderate_field` is used, this must specify the number
+        of days past the value of the field specified by
+        :attr:`auto_moderate_field` after which new comments for an object
+        should be marked non-public. Default value is ``None``.
+
+Simply subclassing :class:`CommentModerator` and changing the values of these
+options will automatically enable the various moderation methods for any
+models registered using the subclass.
+
+Adding custom moderation methods
+--------------------------------
+
+For situations where the built-in options listed above are not
+sufficient, subclasses of :class:`CommentModerator` can also override
+the methods which actually perform the moderation, and apply any logic
+they desire.  :class:`CommentModerator` defines three methods which
+determine how moderation will take place; each method will be called
+by the moderation system and passed two arguments: ``comment``, which
+is the new comment being posted, ``content_object``, which is the
+object the comment will be attached to, and ``request``, which is the
+:class:`~django.http.HttpRequest` in which the comment is being submitted:
+
+.. method:: CommentModerator.allow(comment, content_object, request)
+
+    Should return ``True`` if the comment should be allowed to
+    post on the content object, and ``False`` otherwise (in which
+    case the comment will be immediately deleted).
+
+.. method:: CommentModerator.email(comment, content_object, request)
+
+    If email notification of the new comment should be sent to
+    site staff or moderators, this method is responsible for
+    sending the email.
+
+.. method:: CommentModerator.moderate(comment, content_object, request)
+
+    Should return ``True`` if the comment should be moderated (in
+    which case its ``is_public`` field will be set to ``False``
+    before saving), and ``False`` otherwise (in which case the
+    ``is_public`` field will not be changed).
+
+
+Registering models for moderation
+---------------------------------
+
+The moderation system, represented by
+``django.contrib.comments.moderation.moderator`` is an instance of the class
+:class:`Moderator`, which allows registration and "unregistration" of models
+via two methods:
+
+.. function:: moderator.register(model_or_iterable, moderation_class)
+
+    Takes two arguments: the first should be either a model class
+    or list of model classes, and the second should be a subclass
+    of ``CommentModerator``, and register the model or models to
+    be moderated using the options defined in the
+    ``CommentModerator`` subclass. If any of the models are
+    already registered for moderation, the exception
+    :exc:`AlreadyModerated` will be raised.
+
+.. function:: moderator.unregister(model_or_iterable)
+
+    Takes one argument: a model class or list of model classes,
+    and removes the model or models from the set of models which
+    are being moderated. If any of the models are not currently
+    being moderated, the exception
+    :exc:`NotModerated` will be raised.
+
+
+Customizing the moderation system
+---------------------------------
+
+Most use cases will work easily with simple subclassing of
+:class:`CommentModerator` and registration with the provided
+:class:`Moderator` instance, but customization of global moderation behavior
+can be achieved by subclassing :class:`Moderator` and instead registering
+models with an instance of the subclass.
+
+.. class:: Moderator
+
+    In addition to the :meth:`Moderator.register` and
+    :meth:`Moderator.unregister` methods detailed above, the following methods
+    on :class:`Moderator` can be overridden to achieve customized behavior:
+
+    .. method:: connect
+
+        Determines how moderation is set up globally. The base
+        implementation in
+        :class:`Moderator` does this by
+        attaching listeners to the :data:`~django.contrib.comments.signals.comment_will_be_posted`
+        and :data:`~django.contrib.comments.signals.comment_was_posted` signals from the
+        comment models.
+
+    .. method:: pre_save_moderation(sender, comment, request, **kwargs)
+
+        In the base implementation, applies all pre-save moderation
+        steps (such as determining whether the comment needs to be
+        deleted, or whether it needs to be marked as non-public or
+        generate an email).
+
+    .. method:: post_save_moderation(sender, comment, request, **kwargs)
+
+        In the base implementation, applies all post-save moderation
+        steps (currently this consists entirely of deleting comments
+        which were disallowed).
diff --git a/parts/django/docs/ref/contrib/comments/settings.txt b/parts/django/docs/ref/contrib/comments/settings.txt
new file mode 100644
index 0000000..1f1aeca
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/settings.txt
@@ -0,0 +1,33 @@
+================
+Comment settings
+================
+
+These settings configure the behavior of the comments framework:
+
+.. setting:: COMMENTS_HIDE_REMOVED
+
+COMMENTS_HIDE_REMOVED
+---------------------
+
+If ``True`` (default), removed comments will be excluded from comment
+lists/counts (as taken from template tags). Otherwise, the template author is
+responsible for some sort of a "this comment has been removed by the site staff"
+message.
+
+.. setting:: COMMENT_MAX_LENGTH
+
+COMMENT_MAX_LENGTH
+------------------
+
+The maximum length of the comment field, in characters. Comments longer than
+this will be rejected. Defaults to 3000.
+
+.. setting:: COMMENTS_APP
+
+COMMENTS_APP
+------------
+
+An app which provides :doc:`customization of the comments framework
+</ref/contrib/comments/custom>`.  Use the same dotted-string notation
+as in :setting:`INSTALLED_APPS`.  Your custom :setting:`COMMENTS_APP`
+must also be listed in :setting:`INSTALLED_APPS`.
diff --git a/parts/django/docs/ref/contrib/comments/signals.txt b/parts/django/docs/ref/contrib/comments/signals.txt
new file mode 100644
index 0000000..7ae34a1
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/signals.txt
@@ -0,0 +1,91 @@
+================================
+Signals sent by the comments app
+================================
+
+.. module:: django.contrib.comments.signals
+   :synopsis: Signals sent by the comment module.
+
+The comment app sends a series of :doc:`signals </topics/signals>` to allow for
+comment moderation and similar activities. See :doc:`the introduction to signals
+</topics/signals>` for information about how to register for and receive these
+signals.
+
+comment_will_be_posted
+======================
+
+.. data:: django.contrib.comments.signals.comment_will_be_posted
+   :module:
+
+Sent just before a comment will be saved, after it's been sanity checked and
+submitted. This can be used to modify the comment (in place) with posting
+details or other such actions.
+
+If any receiver returns ``False`` the comment will be discarded and a 403 (not
+allowed) response will be returned.
+
+This signal is sent at more or less the same time (just before, actually) as the
+``Comment`` object's :data:`~django.db.models.signals.pre_save` signal.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance about to be posted. Note that it won't have been
+        saved into the database yet, so it won't have a primary key, and any
+        relations might not work correctly yet.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+        
+comment_was_posted
+==================
+
+.. data:: django.contrib.comments.signals.comment_was_posted
+   :module:
+   
+Sent just after the comment is saved.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
+
+comment_was_flagged
+===================
+
+.. data:: django.contrib.comments.signals.comment_was_flagged
+   :module:
+
+Sent after a comment was "flagged" in some way. Check the flag to see if this
+was a user requesting removal of a comment, a moderator approving/removing a
+comment, or some other custom user flag.
+
+Arguments sent with this signal:
+    
+    ``sender``
+        The comment model.
+        
+    ``comment``
+        The comment instance that was posted. Note that it will have already
+        been saved, so if you modify it you'll need to call
+        :meth:`~django.db.models.Model.save` again.
+        
+    ``flag``
+        The :class:`~django.contrib.comments.models.CommentFlag` that's been
+        attached to the comment.
+        
+    ``created``
+        ``True`` if this is a new flag; ``False`` if it's a duplicate flag.
+        
+    ``request``
+        The :class:`~django.http.HttpRequest` that posted the comment.
diff --git a/parts/django/docs/ref/contrib/comments/upgrade.txt b/parts/django/docs/ref/contrib/comments/upgrade.txt
new file mode 100644
index 0000000..3d6b5af
--- /dev/null
+++ b/parts/django/docs/ref/contrib/comments/upgrade.txt
@@ -0,0 +1,78 @@
+===============================================
+Upgrading from Django's previous comment system
+===============================================
+
+Prior versions of Django included an outdated, undocumented comment system. Users who reverse-engineered this framework will need to upgrade to use the
+new comment system; this guide explains how.
+
+The main changes from the old system are:
+
+    * This new system is documented.
+    
+    * It uses modern Django features like :doc:`forms </topics/forms/index>` and
+      :doc:`modelforms </topics/forms/modelforms>`.
+
+    * It has a single ``Comment`` model instead of separate ``FreeComment`` and
+      ``Comment`` models.
+
+    * Comments have "email" and "URL" fields.
+
+    * No ratings, photos and karma. This should only effect World Online.
+
+    * The ``{% comment_form %}`` tag no longer exists. Instead, there's now two
+      functions: ``{% get_comment_form %}``, which returns a form for posting a
+      new comment, and ``{% render_comment_form %}``, which renders said form
+      using the ``comments/form.html`` template.
+      
+    * The way comments are include in your URLconf have changed; you'll need to
+      replace::
+    
+            (r'^comments/', include('django.contrib.comments.urls.comments')),
+      
+      with::
+
+            (r'^comments/', include('django.contrib.comments.urls')),
+
+Upgrading data
+--------------
+
+The data models for Django's comment system have changed, as have the
+table names. Before you transfer your existing data into the new comments
+system, make sure that you have installed the new comments system as
+explained in the
+:doc:`quick start guide </ref/contrib/comments/index>`.
+This will ensure that the new tables have been properly created.
+
+To transfer your data into the new comments system, you'll need to directly
+run the following SQL:
+
+.. code-block:: sql
+
+    BEGIN;
+
+    INSERT INTO django_comments 
+        (content_type_id, object_pk, site_id, user_name, user_email, user_url,
+        comment, submit_date, ip_address, is_public, is_removed)
+    SELECT
+        content_type_id, object_id, site_id, person_name, '', '', comment,
+        submit_date, ip_address, is_public, not approved
+    FROM comments_freecomment;
+
+    INSERT INTO django_comments 
+        (content_type_id, object_pk, site_id, user_id, user_name, user_email,
+        user_url, comment, submit_date, ip_address, is_public, is_removed)
+    SELECT 
+        content_type_id, object_id, site_id, user_id, '', '', '', comment,
+        submit_date, ip_address, is_public, is_removed
+    FROM comments_comment;
+
+    UPDATE django_comments SET user_name = (
+        SELECT username FROM auth_user 
+        WHERE django_comments.user_id = auth_user.id
+    ) WHERE django_comments.user_id is not NULL;
+    UPDATE django_comments SET user_email = (
+        SELECT email FROM auth_user 
+        WHERE django_comments.user_id = auth_user.id
+    ) WHERE django_comments.user_id is not NULL;
+    
+    COMMIT;
diff --git a/parts/django/docs/ref/contrib/contenttypes.txt b/parts/django/docs/ref/contrib/contenttypes.txt
new file mode 100644
index 0000000..b695651
--- /dev/null
+++ b/parts/django/docs/ref/contrib/contenttypes.txt
@@ -0,0 +1,385 @@
+==========================
+The contenttypes framework
+==========================
+
+.. module:: django.contrib.contenttypes
+   :synopsis: Provides generic interface to installed models.
+
+Django includes a :mod:`contenttypes` application that can track all of
+the models installed in your Django-powered project, providing a
+high-level, generic interface for working with your models.
+
+Overview
+========
+
+At the heart of the contenttypes application is the
+:class:`~django.contrib.contenttypes.models.ContentType` model, which lives at
+``django.contrib.contenttypes.models.ContentType``. Instances of
+:class:`~django.contrib.contenttypes.models.ContentType` represent and store
+information about the models installed in your project, and new instances of
+:class:`~django.contrib.contenttypes.models.ContentType` are automatically
+created whenever new models are installed.
+
+Instances of :class:`~django.contrib.contenttypes.models.ContentType` have
+methods for returning the model classes they represent and for querying objects
+from those models. :class:`~django.contrib.contenttypes.models.ContentType`
+also has a :ref:`custom manager <custom-managers>` that adds methods for
+working with :class:`~django.contrib.contenttypes.models.ContentType` and for
+obtaining instances of :class:`~django.contrib.contenttypes.models.ContentType`
+for a particular model.
+
+Relations between your models and
+:class:`~django.contrib.contenttypes.models.ContentType` can also be used to
+enable "generic" relationships between an instance of one of your
+models and instances of any model you have installed.
+
+Installing the contenttypes framework
+=====================================
+
+The contenttypes framework is included in the default
+:setting:`INSTALLED_APPS` list created by ``django-admin.py startproject``,
+but if you've removed it or if you manually set up your
+:setting:`INSTALLED_APPS` list, you can enable it by adding
+``'django.contrib.contenttypes'`` to your :setting:`INSTALLED_APPS` setting.
+
+It's generally a good idea to have the contenttypes framework
+installed; several of Django's other bundled applications require it:
+
+    * The admin application uses it to log the history of each object
+      added or changed through the admin interface.
+
+    * Django's :mod:`authentication framework <django.contrib.auth>` uses it
+      to tie user permissions to specific models.
+
+    * Django's comments system (:mod:`django.contrib.comments`) uses it to
+      "attach" comments to any installed model.
+
+The ``ContentType`` model
+=========================
+
+.. class:: models.ContentType
+
+    Each instance of :class:`~django.contrib.contenttypes.models.ContentType`
+    has three fields which, taken together, uniquely describe an installed model:
+
+    .. attribute:: models.ContentType.app_label
+
+        The name of the application the model is part of. This is taken from
+        the :attr:`app_label` attribute of the model, and includes only the *last*
+        part of the application's Python import path;
+        "django.contrib.contenttypes", for example, becomes an :attr:`app_label`
+        of "contenttypes".
+
+    .. attribute:: models.ContentType.model
+
+        The name of the model class.
+
+    .. attribute:: models.ContentType.name
+
+        The human-readable name of the model. This is taken from the
+        :attr:`verbose_name <django.db.models.fields.Field.verbose_name>`
+        attribute of the model.
+
+Let's look at an example to see how this works. If you already have
+the contenttypes application installed, and then add
+:mod:`the sites application <django.contrib.sites>` to your
+:setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it,
+the model :class:`django.contrib.sites.models.Site` will be installed into
+your database. Along with it a new instance of
+:class:`~django.contrib.contenttypes.models.ContentType` will be
+created with the following values:
+
+    * :attr:`app_label` will be set to ``'sites'`` (the last part of the Python
+      path "django.contrib.sites").
+
+    * :attr:`model` will be set to ``'site'``.
+
+    * :attr:`name` will be set to ``'site'``.
+
+.. _the verbose_name attribute: ../model-api/#verbose_name
+
+Methods on ``ContentType`` instances
+====================================
+
+.. class:: models.ContentType
+
+    Each :class:`~django.contrib.contenttypes.models.ContentType` instance has
+    methods that allow you to get from a
+    :class:`~django.contrib.contenttypes.models.ContentType` instance to the model
+    it represents, or to retrieve objects from that model:
+
+.. method:: models.ContentType.get_object_for_this_type(**kwargs)
+
+    Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the
+    model the :class:`~django.contrib.contenttypes.models.ContentType`
+    represents, and does :lookup:`a get() lookup <get>` on that model,
+    returning the corresponding object.
+
+.. method:: models.ContentType.model_class()
+
+    Returns the model class represented by this
+    :class:`~django.contrib.contenttypes.models.ContentType` instance.
+
+For example, we could look up the
+:class:`~django.contrib.contenttypes.models.ContentType` for the
+:class:`~django.contrib.auth.models.User` model::
+
+    >>> from django.contrib.contenttypes.models import ContentType
+    >>> user_type = ContentType.objects.get(app_label="auth", model="user")
+    >>> user_type
+    <ContentType: user>
+
+And then use it to query for a particular ``User``, or to get access
+to the ``User`` model class::
+
+    >>> user_type.model_class()
+    <class 'django.contrib.auth.models.User'>
+    >>> user_type.get_object_for_this_type(username='Guido')
+    <User: Guido>
+
+Together,
+:meth:`~django.contrib.contenttypes.models.ContentType.get_object_for_this_type`
+and :meth:`~django.contrib.contenttypes.models.ContentType.model_class`
+enable two extremely important use cases:
+
+    1. Using these methods, you can write high-level generic code that
+       performs queries on any installed model -- instead of importing and using
+       a single specific model class, you can pass an ``app_label`` and
+       ``model`` into a :class:`~django.contrib.contenttypes.models.ContentType`
+       lookup at runtime, and then work with the model class or retrieve objects
+       from it.
+
+    2. You can relate another model to
+       :class:`~django.contrib.contenttypes.models.ContentType` as a way of
+       tying instances of it to particular model classes, and use these methods
+       to get access to those model classes.
+
+Several of Django's bundled applications make use of the latter technique.
+For example,
+:class:`the permissions system <django.contrib.auth.models.Permission` in
+Django's authentication framework uses a
+:class:`~django.contrib.auth.models.Permission` model with a foreign
+key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets
+:class:`~django.contrib.auth.models.Permission` represent concepts like
+"can add blog entry" or "can delete news story".
+
+The ``ContentTypeManager``
+--------------------------
+
+.. class:: models.ContentTypeManager
+
+    :class:`~django.contrib.contenttypes.models.ContentType` also has a custom
+    manager, :class:`~django.contrib.contenttypes.models.ContentTypeManager`,
+    which adds the following methods:
+
+    .. method:: models.ContentTypeManager.clear_cache()
+
+        Clears an internal cache used by
+        :class:`~django.contrib.contenttypes.models.ContentType` to keep track
+        of which models for which it has created
+        :class:`django.contrib.contenttypes.models.ContentType` instances. You
+        probably won't ever need to call this method yourself; Django will call
+        it automatically when it's needed.
+
+    .. method:: models.ContentTypeManager.get_for_model(model)
+
+        Takes either a model class or an instance of a model, and returns the
+        :class:`~django.contrib.contenttypes.models.ContentType` instance
+        representing that model.
+
+The :meth:`~models.ContentTypeManager.get_for_model()` method is especially useful when you know you
+need to work with a :class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't want to go to the
+trouble of obtaining the model's metadata to perform a manual lookup::
+
+    >>> from django.contrib.auth.models import User
+    >>> user_type = ContentType.objects.get_for_model(User)
+    >>> user_type
+    <ContentType: user>
+
+.. _generic-relations:
+
+Generic relations
+=================
+
+Adding a foreign key from one of your own models to
+:class:`~django.contrib.contenttypes.models.ContentType` allows your model to
+effectively tie itself to another model class, as in the example of the
+:class:`~django.contrib.auth.models.Permission` model above. But it's possible
+to go one step further and use
+:class:`~django.contrib.contenttypes.models.ContentType` to enable truly
+generic (sometimes called "polymorphic") relationships between models.
+
+A simple example is a tagging system, which might look like this::
+
+    from django.db import models
+    from django.contrib.contenttypes.models import ContentType
+    from django.contrib.contenttypes import generic
+
+    class TaggedItem(models.Model):
+        tag = models.SlugField()
+        content_type = models.ForeignKey(ContentType)
+        object_id = models.PositiveIntegerField()
+        content_object = generic.GenericForeignKey('content_type', 'object_id')
+
+        def __unicode__(self):
+            return self.tag
+
+A normal :class:`~django.db.models.fields.related.ForeignKey` can only "point
+to" one other model, which means that if the ``TaggedItem`` model used a
+:class:`~django.db.models.fields.related.ForeignKey` it would have to
+choose one and only one model to store tags for. The contenttypes
+application provides a special field type --
+:class:`django.contrib.contenttypes.generic.GenericForeignKey` -- which
+works around this and allows the relationship to be with any
+model. There are three parts to setting up a
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey`:
+
+    1. Give your model a :class:`~django.db.models.fields.related.ForeignKey`
+       to :class:`~django.contrib.contenttypes.models.ContentType`.
+
+    2. Give your model a field that can store a primary-key value from the
+       models you'll be relating to. (For most models, this means an
+       :class:`~django.db.models.fields.IntegerField` or
+       :class:`~django.db.models.fields.PositiveIntegerField`.)
+
+       This field must be of the same type as the primary key of the models
+       that will be involved in the generic relation. For example, if you use
+       :class:`~django.db.models.fields.IntegerField`, you won't be able to
+       form a generic relation with a model that uses a
+       :class:`~django.db.models.fields.CharField` as a primary key.
+
+    3. Give your model a
+       :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and
+       pass it the names of the two fields described above. If these fields
+       are named "content_type" and "object_id", you can omit this -- those
+       are the default field names
+       :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will
+       look for.
+
+This will enable an API similar to the one used for a normal
+:class:`~django.db.models.fields.related.ForeignKey`;
+each ``TaggedItem`` will have a ``content_object`` field that returns the
+object it's related to, and you can also assign to that field or use it when
+creating a ``TaggedItem``::
+
+    >>> from django.contrib.auth.models import User
+    >>> guido = User.objects.get(username='Guido')
+    >>> t = TaggedItem(content_object=guido, tag='bdfl')
+    >>> t.save()
+    >>> t.content_object
+    <User: Guido>
+
+Due to the way :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
+is implemented, you cannot use such fields directly with filters (``filter()``
+and ``exclude()``, for example) via the database API. They aren't normal field
+objects. These examples will *not* work::
+
+    # This will fail
+    >>> TaggedItem.objects.filter(content_object=guido)
+    # This will also fail
+    >>> TaggedItem.objects.get(content_object=guido)
+
+Reverse generic relations
+-------------------------
+
+If you know which models you'll be using most often, you can also add
+a "reverse" generic relationship to enable an additional API. For example::
+
+    class Bookmark(models.Model):
+        url = models.URLField()
+        tags = generic.GenericRelation(TaggedItem)
+
+``Bookmark`` instances will each have a ``tags`` attribute, which can
+be used to retrieve their associated ``TaggedItems``::
+
+    >>> b = Bookmark(url='http://www.djangoproject.com/')
+    >>> b.save()
+    >>> t1 = TaggedItem(content_object=b, tag='django')
+    >>> t1.save()
+    >>> t2 = TaggedItem(content_object=b, tag='python')
+    >>> t2.save()
+    >>> b.tags.all()
+    [<TaggedItem: django>, <TaggedItem: python>]
+
+Just as :class:`django.contrib.contenttypes.generic.GenericForeignKey`
+accepts the names of the content-type and object-ID fields as
+arguments, so too does ``GenericRelation``; if the model which has the
+generic foreign key is using non-default names for those fields, you
+must pass the names of the fields when setting up a
+``GenericRelation`` to it. For example, if the ``TaggedItem`` model
+referred to above used fields named ``content_type_fk`` and
+``object_primary_key`` to create its generic foreign key, then a
+``GenericRelation`` back to it would need to be defined like so::
+
+    tags = generic.GenericRelation(TaggedItem, content_type_field='content_type_fk', object_id_field='object_primary_key')
+
+Of course, if you don't add the reverse relationship, you can do the
+same types of lookups manually::
+
+    >>> b = Bookmark.objects.get(url='http://www.djangoproject.com/')
+    >>> bookmark_type = ContentType.objects.get_for_model(b)
+    >>> TaggedItem.objects.filter(content_type__pk=bookmark_type.id,
+    ...                           object_id=b.id)
+    [<TaggedItem: django>, <TaggedItem: python>]
+
+Note that if the model in a
+:class:`~django.contrib.contenttypes.generic.GenericRelation` uses a
+non-default value for ``ct_field`` or ``fk_field`` in its
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the
+:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``),
+you'll need to set ``content_type_field`` and/or ``object_id_field`` in
+the :class:`~django.contrib.contenttypes.generic.GenericRelation` to
+match the ``ct_field`` and ``fk_field``, respectively, in the
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey`::
+
+	comments = generic.GenericRelation(Comment, object_id_field="object_pk")
+
+Note also, that if you delete an object that has a
+:class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects
+which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
+pointing at it will be deleted as well. In the example above, this means that
+if a ``Bookmark`` object were deleted, any ``TaggedItem`` objects pointing at
+it would be deleted at the same time.
+
+Generic relations and aggregation
+---------------------------------
+
+:doc:`Django's database aggregation API </topics/db/aggregation>`
+doesn't work with a
+:class:`~django.contrib.contenttypes.generic.GenericRelation`. For example, you
+might be tempted to try something like::
+
+    Bookmark.objects.aggregate(Count('tags'))
+
+This will not work correctly, however. The generic relation adds extra filters
+to the queryset to ensure the correct content type, but the ``aggregate`` method
+doesn't take them into account. For now, if you need aggregates on generic
+relations, you'll need to calculate them without using the aggregation API.
+
+Generic relations in forms and admin
+------------------------------------
+
+:mod:`django.contrib.contenttypes.generic` provides both a
+:class:`~django.contrib.contenttypes.generic.GenericInlineFormSet`
+and :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`.
+This enables the use of generic relations in forms and the admin. See the
+:doc:`model formset </topics/forms/modelforms>` and
+:doc:`admin </ref/contrib/admin/index>` documentation for more information.
+
+.. class:: generic.GenericInlineModelAdmin
+
+    The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`
+    class inherits all properties from an
+    :class:`~django.contrib.admin.InlineModelAdmin` class. However,
+    it adds a couple of its own for working with the generic relation:
+
+    .. attribute:: generic.GenericInlineModelAdmin.ct_field
+
+        The name of the
+        :class:`~django.contrib.contenttypes.models.ContentType` foreign key
+        field on the model. Defaults to ``content_type``.
+
+    .. attribute:: generic.GenericInlineModelAdmin.ct_fk_field
+
+        The name of the integer field that represents the ID of the related
+        object. Defaults to ``object_id``.
diff --git a/parts/django/docs/ref/contrib/csrf.txt b/parts/django/docs/ref/contrib/csrf.txt
new file mode 100644
index 0000000..c32dd73
--- /dev/null
+++ b/parts/django/docs/ref/contrib/csrf.txt
@@ -0,0 +1,433 @@
+=====================================
+Cross Site Request Forgery protection
+=====================================
+
+.. module:: django.middleware.csrf
+   :synopsis: Protects against Cross Site Request Forgeries
+
+The CSRF middleware and template tag provides easy-to-use protection against
+`Cross Site Request Forgeries`_.  This type of attack occurs when a malicious
+Web site contains a link, a form button or some javascript that is intended to
+perform some action on your Web site, using the credentials of a logged-in user
+who visits the malicious site in their browser.  A related type of attack,
+'login CSRF', where an attacking site tricks a user's browser into logging into
+a site with someone else's credentials, is also covered.
+
+The first defense against CSRF attacks is to ensure that GET requests are
+side-effect free.  POST requests can then be protected by following the steps
+below.
+
+.. versionadded:: 1.2
+    The 'contrib' apps, including the admin, use the functionality described
+    here. Because it is security related, a few things have been added to core
+    functionality to allow this to happen without any required upgrade steps.
+
+.. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF
+
+How to use it
+=============
+
+.. versionchanged:: 1.2
+    The template tag functionality (the recommended way to use this) was added
+    in version 1.2. The previous method (still available) is described under
+    `Legacy method`_.
+
+To enable CSRF protection for your views, follow these steps:
+
+    1. Add the middleware
+       ``'django.middleware.csrf.CsrfViewMiddleware'`` to your list of
+       middleware classes, :setting:`MIDDLEWARE_CLASSES`.  (It should come
+       before ``CsrfResponseMiddleware`` if that is being used, and before any
+       view middleware that assume that CSRF attacks have been dealt with.)
+
+       Alternatively, you can use the decorator
+       ``django.views.decorators.csrf.csrf_protect`` on particular views you
+       want to protect (see below).
+
+    2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
+       the ``<form>`` element if the form is for an internal URL, e.g.::
+
+           <form action="" method="post">{% csrf_token %}
+
+       This should not be done for POST forms that target external URLs, since
+       that would cause the CSRF token to be leaked, leading to a vulnerability.
+
+    3. In the corresponding view functions, ensure that the
+       ``'django.core.context_processors.csrf'`` context processor is
+       being used. Usually, this can be done in one of two ways:
+
+       1. Use RequestContext, which always uses
+          ``'django.core.context_processors.csrf'`` (no matter what your
+          TEMPLATE_CONTEXT_PROCESSORS setting).  If you are using
+          generic views or contrib apps, you are covered already, since these
+          apps use RequestContext throughout.
+
+       2. Manually import and use the processor to generate the CSRF token and
+          add it to the template context. e.g.::
+
+              from django.core.context_processors import csrf
+              from django.shortcuts import render_to_response
+
+              def my_view(request):
+                  c = {}
+                  c.update(csrf(request))
+                  # ... view code here
+                  return render_to_response("a_template.html", c)
+
+          You may want to write your own ``render_to_response`` wrapper that
+          takes care of this step for you.
+
+The utility script ``extras/csrf_migration_helper.py`` can help to automate the
+finding of code and templates that may need to be upgraded.  It contains full
+help on how to use it.
+
+The decorator method
+--------------------
+
+Rather than adding ``CsrfViewMiddleware`` as a blanket protection, you can use
+the ``csrf_protect`` decorator, which has exactly the same functionality, on
+particular views that need the protection.  It must be used **both** on views
+that insert the CSRF token in the output, and on those that accept the POST form
+data. (These are often the same view function, but not always).  It is used like
+this::
+
+    from django.views.decorators.csrf import csrf_protect
+    from django.template import RequestContext
+
+    @csrf_protect
+    def my_view(request):
+        c = {}
+        # ...
+        return render_to_response("a_template.html", c,
+                                   context_instance=RequestContext(request))
+
+Use of the decorator is **not recommended** by itself, since if you forget to
+use it, you will have a security hole.  The 'belt and braces' strategy of using
+both is fine, and will incur minimal overhead.
+
+Legacy method
+-------------
+
+In Django 1.1, the template tag did not exist.  Instead, a post-processing
+middleware that re-wrote POST forms to include the CSRF token was used.  If you
+are upgrading a site from version 1.1 or earlier, please read this section and
+the `Upgrading notes`_ below.  The post-processing middleware is still available
+as ``CsrfResponseMiddleware``, and it can be used by following these steps:
+
+    1. Follow step 1 above to install ``CsrfViewMiddleware``.
+
+    2. Add ``'django.middleware.csrf.CsrfResponseMiddleware'`` to your
+       :setting:`MIDDLEWARE_CLASSES` setting.
+
+       ``CsrfResponseMiddleware`` needs to process the response before things
+       like compression or setting ofETags happen to the response, so it must
+       come after ``GZipMiddleware``, ``CommonMiddleware`` and
+       ``ConditionalGetMiddleware`` in the list. It also must come after
+       ``CsrfViewMiddleware``.
+
+Use of the ``CsrfResponseMiddleware`` is not recommended because of the
+performance hit it imposes, and because of a potential security problem (see
+below).  It can be used as an interim measure until applications have been
+updated to use the :ttag:`csrf_token` tag.  It is deprecated and will be
+removed in Django 1.4.
+
+Django 1.1 and earlier provided a single ``CsrfMiddleware`` class.  This is also
+still available for backwards compatibility.  It combines the functions of the
+two middleware.
+
+Note also that previous versions of these classes depended on the sessions
+framework, but this dependency has now been removed, with backward compatibility
+support so that upgrading will not produce any issues.
+
+Security of legacy method
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The post-processing ``CsrfResponseMiddleware`` adds the CSRF token to all POST
+forms (unless the view has been decorated with ``csrf_response_exempt``).  If
+the POST form has an external untrusted site as its target, rather than an
+internal page, that site will be sent the CSRF token when the form is submitted.
+Armed with this leaked information, that site will then be able to successfully
+launch a CSRF attack on your site against that user.  The
+``@csrf_response_exempt`` decorator can be used to fix this, but only if the
+page doesn't also contain internal forms that require the token.
+
+.. _ref-csrf-upgrading-notes:
+
+Upgrading notes
+---------------
+
+When upgrading to version 1.2 or later, you may have applications that rely on
+the old post-processing functionality for CSRF protection, or you may not have
+enabled any CSRF protection.  This section outlines the steps necessary for a
+smooth upgrade, without having to fix all the applications to use the new
+template tag method immediately.
+
+First of all, the location of the middleware and related functions have
+changed.  There are backwards compatible stub files so that old imports will
+continue to work for now, but they are deprecated and will be removed in Django
+1.4.  The following changes have been made:
+
+ * Middleware have been moved to ``django.middleware.csrf``
+ * Decorators have been moved to ``django.views.decorators.csrf``
+
+======================================================  ==============================================
+   Old                                                       New
+======================================================  ==============================================
+django.contrib.csrf.middleware.CsrfMiddleware           django.middleware.csrf.CsrfMiddleware
+django.contrib.csrf.middleware.CsrfViewMiddleware       django.middleware.csrf.CsrfViewMiddleware
+django.contrib.csrf.middleware.CsrfResponseMiddleware   django.middleware.csrf.CsrfResponseMiddleware
+django.contrib.csrf.middleware.csrf_exempt              django.views.decorators.csrf.csrf_exempt
+django.contrib.csrf.middleware.csrf_view_exempt         django.views.decorators.csrf.csrf_view_exempt
+django.contrib.csrf.middleware.csrf_response_exempt     django.views.decorators.csrf.csrf_response_exempt
+======================================================  ==============================================
+
+You should update any imports, and also the paths in your
+:setting:`MIDDLEWARE_CLASSES`.
+
+If you have ``CsrfMiddleware`` in your :setting:`MIDDLEWARE_CLASSES`, you will now
+have a working installation with CSRF protection.  It is recommended at this
+point that you replace ``CsrfMiddleware`` with its two components,
+``CsrfViewMiddleware`` and ``CsrfResponseMiddleware`` (in that order).
+
+If you do not have any of the middleware in your :setting:`MIDDLEWARE_CLASSES`,
+you will have a working installation but without any CSRF protection for your
+views (just as you had before). It is strongly recommended to install
+``CsrfViewMiddleware`` and ``CsrfResponseMiddleware``, as described above.
+
+Note that contrib apps, such as the admin, have been updated to use the
+``csrf_protect`` decorator, so that they are secured even if you do not add the
+``CsrfViewMiddleware`` to your settings.  However, if you have supplied
+customised templates to any of the view functions of contrib apps (whether
+explicitly via a keyword argument, or by overriding built-in templates), **you
+MUST update them** to include the :ttag:`csrf_token` template tag as described
+above, or they will stop working.  (If you cannot update these templates for
+some reason, you will be forced to use ``CsrfResponseMiddleware`` for these
+views to continue working).
+
+Note also, if you are using the comments app, and you are not going to add
+``CsrfViewMiddleware`` to your settings (not recommended), you will need to add
+the ``csrf_protect`` decorator to any views that include the comment forms and
+target the comment views (usually using the :ttag:`comment_form_target` template
+tag).
+
+Assuming you have followed the above, all views in your Django site will now be
+protected by the ``CsrfViewMiddleware``.  Contrib apps meet the requirements
+imposed by the ``CsrfViewMiddleware`` using the template tag, and other
+applications in your project will meet its requirements by virtue of the
+``CsrfResponseMiddleware``.
+
+The next step is to update all your applications to use the template tag, as
+described in `How to use it`_, steps 2-3.  This can be done as soon as is
+practical. Any applications that are updated will now require Django 1.1.2 or
+later, since they will use the CSRF template tag which was not available in
+earlier versions. (The template tag in 1.1.2 is actually a no-op that exists
+solely to ease the transition to 1.2 — it allows apps to be created that have
+CSRF protection under 1.2 without requiring users of the apps to upgrade to the
+Django 1.2.X series).
+
+The utility script ``extras/csrf_migration_helper.py`` can help to automate the
+finding of code and templates that may need to be upgraded.  It contains full
+help on how to use it.
+
+Finally, once all applications are upgraded, ``CsrfResponseMiddleware`` can be
+removed from your settings.
+
+While ``CsrfResponseMiddleware`` is still in use, the ``csrf_response_exempt``
+decorator, described in `Exceptions`_, may be useful.  The post-processing
+middleware imposes a performance hit and a potential vulnerability, and any
+views that have been upgraded to use the new template tag method no longer need
+it.
+
+Exceptions
+----------
+
+.. versionadded:: 1.1
+.. versionchanged:: 1.2
+    Import paths for the decorators below were changed.
+
+To manually exclude a view function from being handled by either of the two CSRF
+middleware, you can use the ``csrf_exempt`` decorator, found in the
+``django.views.decorators.csrf`` module. For example::
+
+    from django.views.decorators.csrf import csrf_exempt
+
+    @csrf_exempt
+    def my_view(request):
+        return HttpResponse('Hello world')
+
+Like the middleware, the ``csrf_exempt`` decorator is composed of two parts: a
+``csrf_view_exempt`` decorator and a ``csrf_response_exempt`` decorator, found
+in the same module.  These disable the view protection mechanism
+(``CsrfViewMiddleware``) and the response post-processing
+(``CsrfResponseMiddleware``) respectively.  They can be used individually if
+required.
+
+You don't have to worry about doing this for most AJAX views. Any request sent
+with "X-Requested-With: XMLHttpRequest" is automatically exempt. (See the `How
+it works`_ section.)
+
+Subdomains
+----------
+
+By default, CSRF cookies are specific to the subdomain they are set for.  This
+means that a form served from one subdomain (e.g. server1.example.com) will not
+be able to have a target on another subdomain (e.g. server2.example.com).  This
+restriction can be removed by setting :setting:`CSRF_COOKIE_DOMAIN` to be
+something like ``".example.com"``.
+
+Please note that, with or without use of this setting, this CSRF protection
+mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
+
+Rejected requests
+=================
+
+By default, a '403 Forbidden' response is sent to the user if an incoming
+request fails the checks performed by ``CsrfViewMiddleware``.  This should
+usually only be seen when there is a genuine Cross Site Request Forgery, or
+when, due to a programming error, the CSRF token has not been included with a
+POST form.
+
+No logging is done, and the error message is not very friendly, so you may want
+to provide your own page for handling this condition.  To do this, simply set
+the :setting:`CSRF_FAILURE_VIEW` setting to a dotted path to your own view
+function, which should have the following signature::
+
+    def csrf_failure(request, reason="")
+
+where ``reason`` is a short message (intended for developers or logging, not for
+end users) indicating the reason the request was rejected.
+
+How it works
+============
+
+The CSRF protection is based on the following things:
+
+1. A CSRF cookie that is set to a random value (a session independent nonce, as
+   it is called), which other sites will not have access to.
+
+   This cookie is set by ``CsrfViewMiddleware``.  It is meant to be permanent,
+   but since there is no way to set a cookie that never expires, it is sent with
+   every response that has called ``django.middleware.csrf.get_token()``
+   (the function used internally to retrieve the CSRF token).
+
+2. A hidden form field with the name 'csrfmiddlewaretoken' present in all
+   outgoing POST forms.  The value of this field is the value of the CSRF
+   cookie.
+
+   This part is done by the template tag (and with the legacy method, it is done
+   by ``CsrfResponseMiddleware``).
+
+3. For all incoming POST requests, a CSRF cookie must be present, and the
+   'csrfmiddlewaretoken' field must be present and correct. If it isn't, the
+   user will get a 403 error.
+
+   This check is done by ``CsrfViewMiddleware``.
+
+4. In addition, for HTTPS requests, strict referer checking is done by
+   ``CsrfViewMiddleware``.  This is necessary to address a Man-In-The-Middle
+   attack that is possible under HTTPS when using a session independent nonce,
+   due to the fact that HTTP 'Set-Cookie' headers are (unfortunately) accepted
+   by clients that are talking to a site under HTTPS.  (Referer checking is not
+   done for HTTP requests because the presence of the Referer header is not
+   reliable enough under HTTP.)
+
+This ensures that only forms that have originated from your Web site can be used
+to POST data back.
+
+It deliberately only targets HTTP POST requests (and the corresponding POST
+forms). GET requests ought never to have any potentially dangerous side effects
+(see `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_), and so a CSRF attack with a GET
+request ought to be harmless.
+
+``CsrfResponseMiddleware`` checks the Content-Type before modifying the
+response, and only pages that are served as 'text/html' or
+'application/xml+xhtml' are modified.
+
+AJAX
+----
+
+The middleware tries to be smart about requests that come in via AJAX. Most
+modern JavaScript toolkits send an "X-Requested-With: XMLHttpRequest" HTTP
+header; these requests are detected and automatically *not* handled by this
+middleware.  We can do this safely because, in the context of a browser, the
+header can only be added by using ``XMLHttpRequest``, and browsers already
+implement a same-domain policy for ``XMLHttpRequest``.
+
+For the more recent browsers that relax this same-domain policy, custom headers
+like "X-Requested-With" are only allowed after the browser has done a
+'preflight' check to the server to see if the cross-domain request is allowed,
+using a strictly 'opt in' mechanism, so the exception for AJAX is still safe—if
+the developer has specifically opted in to allowing cross-site AJAX POST
+requests on a specific URL, they obviously don't want the middleware to disallow
+exactly that.
+
+.. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
+
+Caching
+=======
+
+If the :ttag:`csrf_token` template tag is used by a template (or the ``get_token``
+function is called some other way), ``CsrfViewMiddleware`` will add a cookie and
+a ``Vary: Cookie`` header to the response.  Similarly,
+``CsrfResponseMiddleware`` will send the ``Vary: Cookie`` header if it inserted
+a token.  This means that these middleware will play well with the cache
+middleware if it is used as instructed (``UpdateCacheMiddleware`` goes before
+all other middleware).
+
+However, if you use cache decorators on individual views, the CSRF middleware
+will not yet have been able to set the Vary header.  In this case, on any views
+that will require a CSRF token to be inserted you should use the
+:func:`django.views.decorators.vary.vary_on_cookie` decorator first::
+
+  from django.views.decorators.cache import cache_page
+  from django.views.decorators.vary import vary_on_cookie
+
+  @cache_page(60 * 15)
+  @vary_on_cookie
+  def my_view(request):
+      # ...
+
+
+Testing
+=======
+
+The ``CsrfViewMiddleware`` will usually be a big hindrance to testing view
+functions, due to the need for the CSRF token which must be sent with every POST
+request.  For this reason, Django's HTTP client for tests has been modified to
+set a flag on requests which relaxes the middleware and the ``csrf_protect``
+decorator so that they no longer rejects requests.  In every other respect
+(e.g. sending cookies etc.), they behave the same.
+
+If, for some reason, you *want* the test client to perform CSRF
+checks, you can create an instance of the test client that enforces
+CSRF checks::
+
+    >>> from django.test import Client
+    >>> csrf_client = Client(enforce_csrf_checks=True)
+
+Limitations
+===========
+
+Subdomains within a site will be able to set cookies on the client for the whole
+domain.  By setting the cookie and using a corresponding token, subdomains will
+be able to circumvent the CSRF protection.  The only way to avoid this is to
+ensure that subdomains are controlled by trusted users (or, are at least unable
+to set cookies).  Note that even without CSRF, there are other vulnerabilities,
+such as session fixation, that make giving subdomains to untrusted parties a bad
+idea, and these vulnerabilities cannot easily be fixed with current browsers.
+
+If you are using ``CsrfResponseMiddleware`` and your app creates HTML pages and
+forms in some unusual way, (e.g.  it sends fragments of HTML in JavaScript
+document.write statements) you might bypass the filter that adds the hidden
+field to the form, in which case form submission will always fail.  You should
+use the template tag or :meth:`django.middleware.csrf.get_token` to get
+the CSRF token and ensure it is included when your form is submitted.
+
+Contrib and reusable apps
+=========================
+
+Because it is possible for the developer to turn off the ``CsrfViewMiddleware``,
+all relevant views in contrib apps use the ``csrf_protect`` decorator to ensure
+the security of these applications against CSRF.  It is recommended that the
+developers of other reusable apps that want the same guarantees also use the
+``csrf_protect`` decorator on their views.
diff --git a/parts/django/docs/ref/contrib/databrowse.txt b/parts/django/docs/ref/contrib/databrowse.txt
new file mode 100644
index 0000000..33c8228
--- /dev/null
+++ b/parts/django/docs/ref/contrib/databrowse.txt
@@ -0,0 +1,90 @@
+==========
+Databrowse
+==========
+
+.. module:: django.contrib.databrowse
+   :synopsis: Databrowse is a Django application that lets you browse your data.
+
+Databrowse is a Django application that lets you browse your data.
+
+As the Django admin dynamically creates an admin interface by introspecting
+your models, Databrowse dynamically creates a rich, browsable Web site by
+introspecting your models.
+
+.. admonition:: Note
+
+    Databrowse is **very** new and is currently under active development. It
+    may change substantially before the next Django release.
+
+    With that said, it's easy to use, and it doesn't require writing any
+    code. So you can play around with it today, with very little investment in
+    time or coding.
+
+How to use Databrowse
+=====================
+
+    1. Point Django at the default Databrowse templates. There are two ways to
+       do this:
+
+       * Add ``'django.contrib.databrowse'`` to your :setting:`INSTALLED_APPS`
+         setting. This will work if your :setting:`TEMPLATE_LOADERS` setting
+         includes the ``app_directories`` template loader (which is the case by
+         default). See the :ref:`template loader docs <template-loaders>` for
+         more.
+
+       * Otherwise, determine the full filesystem path to the
+         :file:`django/contrib/databrowse/templates` directory, and add that
+         directory to your :setting:`TEMPLATE_DIRS` setting.
+
+    2. Register a number of models with the Databrowse site::
+
+           from django.contrib import databrowse
+           from myapp.models import SomeModel, SomeOtherModel
+
+           databrowse.site.register(SomeModel)
+           databrowse.site.register(SomeOtherModel)
+
+       Note that you should register the model *classes*, not instances.
+
+       It doesn't matter where you put this, as long as it gets executed at some
+       point. A good place for it is in your :doc:`URLconf file
+       </topics/http/urls>` (``urls.py``).
+
+    3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module::
+
+           from django.contrib import databrowse
+
+       ...and add the following line to your URLconf::
+
+           (r'^databrowse/(.*)', databrowse.site.root),
+
+       The prefix doesn't matter -- you can use ``databrowse/`` or ``db/`` or
+       whatever you'd like.
+
+    4. Run the Django server and visit ``/databrowse/`` in your browser.
+
+Requiring user login
+====================
+
+You can restrict access to logged-in users with only a few extra lines of
+code. Simply add the following import to your URLconf::
+
+    from django.contrib.auth.decorators import login_required
+
+Then modify the :doc:`URLconf </topics/http/urls>` so that the
+:func:`databrowse.site.root` view is decorated with
+:func:`django.contrib.auth.decorators.login_required`::
+
+    (r'^databrowse/(.*)', login_required(databrowse.site.root)),
+
+If you haven't already added support for user logins to your :doc:`URLconf
+</topics/http/urls>`, as described in the :doc:`user authentication docs
+</ref/contrib/auth>`, then you will need to do so now with the following
+mapping::
+
+    (r'^accounts/login/$', 'django.contrib.auth.views.login'),
+
+The final step is to create the login form required by
+:func:`django.contrib.auth.views.login`. The
+:doc:`user authentication docs </ref/contrib/auth>` provide full details and a
+sample template that can be used for this purpose.
diff --git a/parts/django/docs/ref/contrib/flatpages.txt b/parts/django/docs/ref/contrib/flatpages.txt
new file mode 100644
index 0000000..46b28dc
--- /dev/null
+++ b/parts/django/docs/ref/contrib/flatpages.txt
@@ -0,0 +1,167 @@
+=================
+The flatpages app
+=================
+
+.. module:: django.contrib.flatpages
+   :synopsis: A framework for managing simple ?flat? HTML content in a database.
+
+Django comes with an optional "flatpages" application. It lets you store simple
+"flat" HTML content in a database and handles the management for you via
+Django's admin interface and a Python API.
+
+A flatpage is a simple object with a URL, title and content. Use it for
+one-off, special-case pages, such as "About" or "Privacy Policy" pages, that
+you want to store in a database but for which you don't want to develop a
+custom Django application.
+
+A flatpage can use a custom template or a default, systemwide flatpage
+template. It can be associated with one, or multiple, sites.
+
+.. versionadded:: 1.0
+
+The content field may optionally be left blank if you prefer to put your 
+content in a custom template.
+
+Here are some examples of flatpages on Django-powered sites:
+
+    * http://www.lawrence.com/about/contact/
+    * http://www2.ljworld.com/site/rules/
+
+Installation
+============
+
+To install the flatpages app, follow these steps:
+
+    1. Install the :mod:`sites framework <django.contrib.sites>` by adding
+       ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting,
+       if it's not already in there.
+       
+       Also make sure you've correctly set :setting:`SITE_ID` to the ID of the
+       site the settings file represents. This will usually be ``1`` (i.e.
+       ``SITE_ID = 1``, but if you're using the sites framework to manage
+       multiple sites, it could be the ID of a different site.
+       
+    2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS`
+       setting.
+       
+    3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
+       to your :setting:`MIDDLEWARE_CLASSES` setting.
+       
+    4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
+ 
+How it works
+============
+
+``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
+and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
+that simply maps a URL to a title and bunch of text content.
+``django_flatpage_sites`` associates a flatpage with a site.
+
+The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
+does all of the work. Each time any Django application raises a 404 error, this
+middleware checks the flatpages database for the requested URL as a last resort.
+Specifically, it checks for a flatpage with the given URL with a site ID that
+corresponds to the :setting:`SITE_ID` setting.
+
+If it finds a match, it follows this algorithm:
+
+    * If the flatpage has a custom template, it loads that template. Otherwise,
+      it loads the template :file:`flatpages/default.html`.
+    
+    * It passes that template a single context variable, :data:`flatpage`, which
+      is the flatpage object. It uses
+      :class:`~django.template.context.RequestContext` in rendering the
+      template.
+
+If it doesn't find a match, the request continues to be processed as usual.
+
+The middleware only gets activated for 404s -- not for 500s or responses of any
+other status code.
+
+.. admonition:: Flatpages will not apply view middleware
+
+   Because the ``FlatpageFallbackMiddleware`` is applied only after
+   URL resolution has failed and produced a 404, the response it
+   returns will not apply any :ref:`view middleware <view-middleware>`
+   methods. Only requests which are successfully routed to a view via
+   normal URL resolution apply view middleware.
+
+Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can
+put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at
+the end of the list, because it's a last resort.
+
+For more on middleware, read the :doc:`middleware docs
+</topics/http/middleware>`.
+
+.. admonition:: Ensure that your 404 template works
+    
+    Note that the
+    :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
+    only steps in once another view has successfully produced a 404 response.
+    If another view or middleware class attempts to produce a 404 but ends up
+    raising an exception instead (such as a ``TemplateDoesNotExist``
+    exception if your site does not have an appropriate template to
+    use for HTTP 404 responses), the response will become an HTTP 500
+    ("Internal Server Error") and the
+    :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
+    will not attempt to serve a flat page.
+
+How to add, change and delete flatpages
+=======================================
+
+Via the admin interface
+-----------------------
+
+If you've activated the automatic Django admin interface, you should see a
+"Flatpages" section on the admin index page. Edit flatpages as you edit any
+other object in the system.
+
+Via the Python API
+------------------
+
+.. class:: models.FlatPage
+
+    Flatpages are represented by a standard
+    :doc:`Django model </topics/db/models>`,
+    which lives in `django/contrib/flatpages/models.py`_. You can access
+    flatpage objects via the :doc:`Django database API </topics/db/queries>`.
+
+.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
+
+Flatpage templates
+==================
+
+By default, flatpages are rendered via the template
+:file:`flatpages/default.html`, but you can override that for a
+particular flatpage: in the admin, a collapsed fieldset titled
+"Advanced options" (clicking will expand it) contains a field for
+specifying a template name. If you're creating a flat page via the
+Python API you can simply set the template name as the field
+``template_name`` on the ``FlatPage`` object.
+
+Creating the :file:`flatpages/default.html` template is your responsibility;
+in your template directory, just create a :file:`flatpages` directory
+containing a file :file:`default.html`.
+
+Flatpage templates are passed a single context variable, :data:`flatpage`,
+which is the flatpage object.
+
+Here's a sample :file:`flatpages/default.html` template:
+
+.. code-block:: html+django
+
+    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
+        "http://www.w3.org/TR/REC-html40/loose.dtd">
+    <html>
+    <head>
+    <title>{{ flatpage.title }}</title>
+    </head>
+    <body>
+    {{ flatpage.content }}
+    </body>
+    </html>
+
+Since you're already entering raw HTML into the admin page for a flatpage,
+both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
+requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
+template.
diff --git a/parts/django/docs/ref/contrib/formtools/form-preview.txt b/parts/django/docs/ref/contrib/formtools/form-preview.txt
new file mode 100644
index 0000000..a2cbea7
--- /dev/null
+++ b/parts/django/docs/ref/contrib/formtools/form-preview.txt
@@ -0,0 +1,121 @@
+============
+Form preview
+============
+
+.. module:: django.contrib.formtools
+    :synopsis: Displays an HTML form, forces a preview, then does something
+               with the submission.
+
+Django comes with an optional "form preview" application that helps automate
+the following workflow:
+
+"Display an HTML form, force a preview, then do something with the submission."
+
+To force a preview of a form submission, all you have to do is write a short
+Python class.
+
+Overview
+=========
+
+Given a :class:`django.forms.Form` subclass that you define, this
+application takes care of the following workflow:
+
+   1. Displays the form as HTML on a Web page.
+   2. Validates the form data when it's submitted via POST.
+      a. If it's valid, displays a preview page.
+      b. If it's not valid, redisplays the form with error messages.
+   3. When the "confirmation" form is submitted from the preview page, calls
+      a hook that you define -- a
+      :meth:`~django.contrib.formtools.FormPreview.done()` method that gets
+      passed the valid data.
+
+The framework enforces the required preview by passing a shared-secret hash to
+the preview page via hidden form fields. If somebody tweaks the form parameters
+on the preview page, the form submission will fail the hash-comparison test.
+
+How to use ``FormPreview``
+==========================
+
+    1. Point Django at the default FormPreview templates. There are two ways to
+       do this:
+
+            * Add ``'django.contrib.formtools'`` to your
+              :setting:`INSTALLED_APPS` setting. This will work if your
+              :setting:`TEMPLATE_LOADERS` setting includes the
+              ``app_directories`` template loader (which is the case by
+              default). See the :ref:`template loader docs <template-loaders>`
+              for more.
+
+            * Otherwise, determine the full filesystem path to the
+              :file:`django/contrib/formtools/templates` directory, and add that
+              directory to your :setting:`TEMPLATE_DIRS` setting.
+
+    2. Create a :class:`~django.contrib.formtools.FormPreview` subclass that
+       overrides the :meth:`~django.contrib.formtools.FormPreview.done()`
+       method::
+
+           from django.contrib.formtools.preview import FormPreview
+           from myapp.models import SomeModel
+
+           class SomeModelFormPreview(FormPreview):
+
+               def done(self, request, cleaned_data):
+                   # Do something with the cleaned_data, then redirect
+                   # to a "success" page.
+                   return HttpResponseRedirect('/form/success')
+
+       This method takes an :class:`~django.http.HttpRequest` object and a
+       dictionary of the form data after it has been validated and cleaned.
+       It should return an :class:`~django.http.HttpResponseRedirect` that
+       is the end result of the form being submitted.
+
+    3. Change your URLconf to point to an instance of your
+       :class:`~django.contrib.formtools.FormPreview` subclass::
+
+           from myapp.preview import SomeModelFormPreview
+           from myapp.forms import SomeModelForm
+           from django import forms
+
+       ...and add the following line to the appropriate model in your URLconf::
+
+           (r'^post/$', SomeModelFormPreview(SomeModelForm)),
+
+       where ``SomeModelForm`` is a Form or ModelForm class for the model.
+
+    4. Run the Django server and visit :file:`/post/` in your browser.
+
+``FormPreview`` classes
+=======================
+
+.. class:: FormPreview
+
+A :class:`~django.contrib.formtools.FormPreview` class is a simple Python class
+that represents the preview workflow.
+:class:`~django.contrib.formtools.FormPreview` classes must subclass
+``django.contrib.formtools.preview.FormPreview`` and override the
+:meth:`~django.contrib.formtools.FormPreview.done()` method. They can live
+anywhere in your codebase.
+
+``FormPreview`` templates
+=========================
+
+By default, the form is rendered via the template :file:`formtools/form.html`,
+and the preview page is rendered via the template :file:`formtools/preview.html`.
+These values can be overridden for a particular form preview by setting
+:attr:`~django.contrib.formtools.FormPreview.preview_template` and
+:attr:`~django.contrib.formtools.FormPreview.form_template` attributes on the
+FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
+default templates.
+
+Advanced ``FormPreview`` methods
+================================
+
+.. versionadded:: 1.2
+
+.. method:: FormPreview.process_preview
+
+    Given a validated form, performs any extra processing before displaying the
+    preview page, and saves any extra data in context.
+
+    By default, this method is empty.  It is called after the form is validated,
+    but before the context is modified with hash information and rendered.
diff --git a/parts/django/docs/ref/contrib/formtools/form-wizard.txt b/parts/django/docs/ref/contrib/formtools/form-wizard.txt
new file mode 100644
index 0000000..390d575
--- /dev/null
+++ b/parts/django/docs/ref/contrib/formtools/form-wizard.txt
@@ -0,0 +1,312 @@
+===========
+Form wizard
+===========
+
+.. module:: django.contrib.formtools.wizard
+    :synopsis: Splits forms across multiple Web pages.
+
+.. versionadded:: 1.0
+
+Django comes with an optional "form wizard" application that splits
+:doc:`forms </topics/forms/index>` across multiple Web pages. It maintains
+state in hashed HTML :samp:`<input type="hidden">` fields, and the data isn't
+processed server-side until the final form is submitted.
+
+You might want to use this if you have a lengthy form that would be too
+unwieldy for display on a single page. The first page might ask the user for
+core information, the second page might ask for less important information,
+etc.
+
+The term "wizard," in this context, is `explained on Wikipedia`_.
+
+.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29
+.. _forms: ../forms/
+
+How it works
+============
+
+Here's the basic workflow for how a user would use a wizard:
+
+    1. The user visits the first page of the wizard, fills in the form and
+       submits it.
+    2. The server validates the data. If it's invalid, the form is displayed
+       again, with error messages. If it's valid, the server calculates a
+       secure hash of the data and presents the user with the next form,
+       saving the validated data and hash in :samp:`<input type="hidden">`
+       fields.
+    3. Step 1 and 2 repeat, for every subsequent form in the wizard.
+    4. Once the user has submitted all the forms and all the data has been
+       validated, the wizard processes the data -- saving it to the database,
+       sending an e-mail, or whatever the application needs to do.
+
+Usage
+=====
+
+This application handles as much machinery for you as possible. Generally, you
+just have to do these things:
+
+    1. Define a number of :class:`~django.forms.Form` classes -- one per wizard
+       page.
+
+    2. Create a :class:`FormWizard` class that specifies what to do once all of
+       your forms have been submitted and validated. This also lets you
+       override some of the wizard's behavior.
+
+    3. Create some templates that render the forms. You can define a single,
+       generic template to handle every one of the forms, or you can define a
+       specific template for each form.
+
+    4. Point your URLconf at your :class:`FormWizard` class.
+
+Defining ``Form`` classes
+=========================
+
+The first step in creating a form wizard is to create the
+:class:`~django.forms.Form` classes.  These should be standard
+:class:`django.forms.Form` classes, covered in the :doc:`forms documentation
+</topics/forms/index>`.  These classes can live anywhere in your codebase, but
+convention is to put them in a file called :file:`forms.py` in your
+application.
+
+For example, let's write a "contact form" wizard, where the first page's form
+collects the sender's e-mail address and subject, and the second page collects
+the message itself. Here's what the :file:`forms.py` might look like::
+
+    from django import forms
+
+    class ContactForm1(forms.Form):
+        subject = forms.CharField(max_length=100)
+        sender = forms.EmailField()
+
+    class ContactForm2(forms.Form):
+        message = forms.CharField(widget=forms.Textarea)
+
+**Important limitation:** Because the wizard uses HTML hidden fields to store
+data between pages, you may not include a :class:`~django.forms.FileField`
+in any form except the last one.
+
+Creating a ``FormWizard`` class
+===============================
+
+The next step is to create a
+:class:`django.contrib.formtools.wizard.FormWizard` subclass.  As with your
+:class:`~django.forms.Form` classes, this :class:`FormWizard` class can live
+anywhere in your codebase, but convention is to put it in :file:`forms.py`.
+
+The only requirement on this subclass is that it implement a
+:meth:`~FormWizard.done()` method.
+
+.. method:: FormWizard.done
+
+    This method specifies what should happen when the data for *every* form is
+    submitted and validated.  This method is passed two arguments:
+
+        * ``request`` -- an :class:`~django.http.HttpRequest` object
+        * ``form_list`` -- a list of :class:`~django.forms.Form` classes
+
+In this simplistic example, rather than perform any database operation, the
+method simply renders a template of the validated data::
+
+    from django.shortcuts import render_to_response
+    from django.contrib.formtools.wizard import FormWizard
+
+    class ContactWizard(FormWizard):
+        def done(self, request, form_list):
+            return render_to_response('done.html', {
+                'form_data': [form.cleaned_data for form in form_list],
+            })
+
+Note that this method will be called via ``POST``, so it really ought to be a
+good Web citizen and redirect after processing the data. Here's another
+example::
+
+    from django.http import HttpResponseRedirect
+    from django.contrib.formtools.wizard import FormWizard
+
+    class ContactWizard(FormWizard):
+        def done(self, request, form_list):
+            do_something_with_the_form_data(form_list)
+            return HttpResponseRedirect('/page-to-redirect-to-when-done/')
+
+See the section `Advanced FormWizard methods`_ below to learn about more
+:class:`FormWizard` hooks.
+
+Creating templates for the forms
+================================
+
+Next, you'll need to create a template that renders the wizard's forms. By
+default, every form uses a template called :file:`forms/wizard.html`. (You can
+change this template name by overriding :meth:`~FormWizard.get_template()`,
+which is documented below. This hook also allows you to use a different
+template for each form.)
+
+This template expects the following context:
+
+    * ``step_field`` -- The name of the hidden field containing the step.
+    * ``step0`` -- The current step (zero-based).
+    * ``step`` -- The current step (one-based).
+    * ``step_count`` -- The total number of steps.
+    * ``form`` -- The :class:`~django.forms.Form` instance for the current step
+      (either empty or with errors).
+    * ``previous_fields`` -- A string representing every previous data field,
+      plus hashes for completed forms, all in the form of hidden fields. Note
+      that you'll need to run this through the :tfilter:`safe` template filter,
+      to prevent auto-escaping, because it's raw HTML.
+
+You can supply extra context to this template in two ways:
+
+    * Set the :attr:`~FormWizard.extra_context` attribute on your
+      :class:`FormWizard` subclass to a dictionary.
+
+    * Pass a dictionary as a parameter named ``extra_context`` to your wizard's
+      URL pattern in your URLconf.  See :ref:`hooking-wizard-into-urlconf`.
+
+Here's a full example template:
+
+.. code-block:: html+django
+
+    {% extends "base.html" %}
+
+    {% block content %}
+    <p>Step {{ step }} of {{ step_count }}</p>
+    <form action="." method="post">{% csrf_token %}
+    <table>
+    {{ form }}
+    </table>
+    <input type="hidden" name="{{ step_field }}" value="{{ step0 }}" />
+    {{ previous_fields|safe }}
+    <input type="submit">
+    </form>
+    {% endblock %}
+
+Note that ``previous_fields``, ``step_field`` and ``step0`` are all required
+for the wizard to work properly.
+
+.. _hooking-wizard-into-urlconf:
+
+Hooking the wizard into a URLconf
+=================================
+
+Finally, we need to specify which forms to use in the wizard, and then
+deploy the new :class:`FormWizard` object a URL in ``urls.py``. The
+wizard takes a list of your :class:`~django.forms.Form` objects as
+arguments when you instantiate the Wizard::
+
+    from django.conf.urls.defaults import *
+    from testapp.forms import ContactForm1, ContactForm2, ContactWizard
+
+    urlpatterns = patterns('',
+        (r'^contact/$', ContactWizard([ContactForm1, ContactForm2])),
+    )
+
+Advanced ``FormWizard`` methods
+===============================
+
+.. class:: FormWizard
+
+    Aside from the :meth:`~done()` method, :class:`FormWizard` offers a few
+    advanced method hooks that let you customize how your wizard works.
+
+    Some of these methods take an argument ``step``, which is a zero-based
+    counter representing the current step of the wizard. (E.g., the first form
+    is ``0`` and the second form is ``1``.)
+
+.. method:: FormWizard.prefix_for_step
+
+    Given the step, returns a form prefix to use.  By default, this simply uses
+    the step itself. For more, see the :ref:`form prefix documentation
+    <form-prefix>`.
+
+    Default implementation::
+
+        def prefix_for_step(self, step):
+            return str(step)
+
+.. method:: FormWizard.render_hash_failure
+
+    Renders a template if the hash check fails. It's rare that you'd need to
+    override this.
+
+    Default implementation::
+
+        def render_hash_failure(self, request, step):
+            return self.render(self.get_form(step), request, step,
+                context={'wizard_error':
+                             'We apologize, but your form has expired. Please'
+                             ' continue filling out the form from this page.'})
+
+.. method:: FormWizard.security_hash
+
+    Calculates the security hash for the given request object and
+    :class:`~django.forms.Form` instance.
+
+    By default, this uses an MD5 hash of the form data and your
+    :setting:`SECRET_KEY` setting. It's rare that somebody would need to
+    override this.
+
+    Example::
+
+        def security_hash(self, request, form):
+            return my_hash_function(request, form)
+
+.. method:: FormWizard.parse_params
+
+    A hook for saving state from the request object and ``args`` / ``kwargs``
+    that were captured from the URL by your URLconf.
+
+    By default, this does nothing.
+
+    Example::
+
+        def parse_params(self, request, *args, **kwargs):
+            self.my_state = args[0]
+
+.. method:: FormWizard.get_template
+
+    Returns the name of the template that should be used for the given step.
+
+    By default, this returns :file:`'forms/wizard.html'`, regardless of step.
+
+    Example::
+
+        def get_template(self, step):
+            return 'myapp/wizard_%s.html' % step
+
+    If :meth:`~FormWizard.get_template` returns a list of strings, then the
+    wizard will use the template system's
+    :func:`~django.template.loader.select_template` function.
+    This means the system will use the first template that exists on the
+    filesystem. For example::
+
+        def get_template(self, step):
+            return ['myapp/wizard_%s.html' % step, 'myapp/wizard.html']
+
+.. method:: FormWizard.render_template
+
+    Renders the template for the given step, returning an
+    :class:`~django.http.HttpResponse` object.
+
+    Override this method if you want to add a custom context, return a
+    different MIME type, etc. If you only need to override the template name,
+    use :meth:`~FormWizard.get_template` instead.
+
+    The template will be rendered with the context documented in the
+    "Creating templates for the forms" section above.
+
+.. method:: FormWizard.process_step
+
+    Hook for modifying the wizard's internal state, given a fully validated
+    :class:`~django.forms.Form` object. The Form is guaranteed to have clean,
+    valid data.
+
+    This method should *not* modify any of that data. Rather, it might want to
+    set ``self.extra_context`` or dynamically alter ``self.form_list``, based
+    on previously submitted forms.
+
+    Note that this method is called every time a page is rendered for *all*
+    submitted steps.
+
+    The function signature::
+
+        def process_step(self, request, form, step):
+            # ...
diff --git a/parts/django/docs/ref/contrib/formtools/index.txt b/parts/django/docs/ref/contrib/formtools/index.txt
new file mode 100644
index 0000000..f364706
--- /dev/null
+++ b/parts/django/docs/ref/contrib/formtools/index.txt
@@ -0,0 +1,10 @@
+django.contrib.formtools
+========================
+
+A set of high-level abstractions for Django forms (:mod:`django.forms`).
+
+.. toctree::
+   :maxdepth: 1
+
+   form-preview
+   form-wizard
diff --git a/parts/django/docs/ref/contrib/gis/admin.txt b/parts/django/docs/ref/contrib/gis/admin.txt
new file mode 100644
index 0000000..011bb6b
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/admin.txt
@@ -0,0 +1,72 @@
+.. _ref-gis-admin:
+
+======================
+GeoDjango's admin site
+======================
+
+.. module:: django.contrib.gis.admin
+   :synopsis: GeoDjango's extensions to the admin site.
+
+
+``GeoModelAdmin``
+=================
+
+.. class:: GeoModelAdmin
+
+   .. attribute:: default_lon
+
+   The default center longitude.
+
+   .. attribute:: default_lat
+
+   The default center latitude.
+
+   .. attribute:: default_zoom
+
+   The default zoom level to use.  Defaults to 18.
+
+   .. attribute:: extra_js
+
+   Sequence of URLs to any extra JavaScript to include.
+
+   .. attribute:: map_template
+
+   Override the template used to generate the JavaScript slippy map.
+   Default is ``'gis/admin/openlayers.html'``.
+
+   .. attribute:: map_width
+
+   Width of the map, in pixels.  Defaults to 600.
+
+   .. attribute:: map_height
+
+   Height of the map, in pixels.  Defaults to 400.
+
+   .. attribute:: openlayers_url
+
+   Link to the URL of the OpenLayers JavaScript.  Defaults to
+   ``'http://openlayers.org/api/2.8/OpenLayers.js'``.
+
+
+   .. attribute:: modifiable
+
+   Defaults to ``False``.  When set to to ``True``, disables editing of
+   existing geometry fields in the admin.
+
+   .. note::
+
+       This is different from adding the geometry field to
+       :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`,
+       which will only display the WKT of the geometry. Setting
+       ``modifiable=False``, actually displays the geometry in a map,
+       but disables the ability to edit its vertices.
+
+``OSMGeoAdmin``
+===============
+
+.. class:: OSMGeoAdmin
+
+   A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection
+   with `OpenStreetMap <http://openstreetmap.org/>`_ street data tiles.
+   See the :ref:`OSMGeoAdmin introduction <osmgeoadmin-intro>`
+   in the tutorial for a usage example.
diff --git a/parts/django/docs/ref/contrib/gis/commands.txt b/parts/django/docs/ref/contrib/gis/commands.txt
new file mode 100644
index 0000000..3dd161c
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/commands.txt
@@ -0,0 +1,83 @@
+.. ref-geodjango-admin:
+
+=============================
+GeoDjango Management Commands
+=============================
+
+inspectdb
+=========
+
+.. describe:: django-admin.py inspectdb
+
+When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the
+:djadmin:`inspectdb` management command is overridden with one from GeoDjango.
+The overridden command is spatially-aware, and places geometry fields in the
+auto-generated model definition, where appropriate.
+
+ogrinspect <data_source> <model_name>
+=====================================
+
+.. django-admin:: ogrinspect
+
+The ``ogrinpsect`` management command will inspect the given OGR-compatible
+:class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will
+output a GeoDjango model with the given model name.  There's a detailed example
+of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
+
+.. django-admin-option:: --blank <blank_field(s)>
+
+   Use a comma separated list of OGR field names to add the ``blank=True``
+   keyword option to the field definition.  Set with ``true`` to apply
+   to all applicable fields.
+
+.. django-admin-option:: --decimal <decimal_field(s)>
+
+   Use a comma separated list of OGR float fields to generate
+   :class:`~django.db.models.DecimalField` instead of the default
+   :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all
+   OGR float fields.
+
+.. django-admin-option:: --geom-name <name>
+
+   Specifies the model attribute name to use for the geometry field.
+   Defaults to ``'geom'``.
+
+.. django-admin-option:: --layer <layer>
+
+   The key for specifying which layer in the OGR
+   :class:`~django.contrib.gis.gdal.DataSource` source to use.
+   Defaults to 0 (the first layer). May be an integer or a string identifier
+   for the :class:`~django.contrib.gis.gdal.Layer`.
+
+.. django-admin-option:: --mapping
+
+   Automatically generate a mapping dictionary for use with
+   :class:`~django.contrib.gis.utils.LayerMapping`.
+
+.. django-admin-option:: --multi-geom
+
+   When generating the geometry field, treat it as a geometry collection.
+   For example, if this setting is enabled then a
+   :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed
+   in the generated model rather than
+   :class:`~django.contrib.gis.db.models.PolygonField`.
+
+.. django-admin-option:: --name-field <name_field>
+
+   Generates a ``__unicode__`` routine on the model that will return the
+   the given field name.
+
+.. django-admin-option:: --no-imports
+
+   Suppresses the ``from django.contrib.gis.db import models`` import statement.
+
+.. django-admin-option:: --null <null_field(s)>
+
+   Use a comma separated list of OGR field names to add the ``null=True``
+   keyword option to the field definition.  Set with ``true`` to apply to
+   all applicable fields.
+
+.. django-admin-option:: --srid
+
+   The SRID to use for the geometry field.  If not set, ``ogrinspect`` attempts
+   to automatically determine of the SRID of the data source.
diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh
new file mode 100755
index 0000000..c9ab4fc
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh
new file mode 100755
index 0000000..57a1373
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh
new file mode 100755
index 0000000..081b5f2
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh
new file mode 100755
index 0000000..46bd074
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=/usr/share/postgresql-8.3-postgis
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
diff --git a/parts/django/docs/ref/contrib/gis/db-api.txt b/parts/django/docs/ref/contrib/gis/db-api.txt
new file mode 100644
index 0000000..fbced8e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/db-api.txt
@@ -0,0 +1,349 @@
+.. _ref-gis-db-api:
+
+======================
+GeoDjango Database API
+======================
+
+.. module:: django.contrib.gis.db.models
+   :synopsis: GeoDjango's database API.
+
+.. _spatial-backends:
+
+Spatial Backends
+================
+
+.. versionadded:: 1.2
+
+In Django 1.2, support for :doc:`multiple databases </topics/db/multi-db>` was
+introduced.  In order to support multiple databases, GeoDjango has segregated
+its functionality into full-fledged spatial database backends:
+
+* :mod:`django.contrib.gis.db.backends.postgis`
+* :mod:`django.contrib.gis.db.backends.mysql`
+* :mod:`django.contrib.gis.db.backends.oracle`
+* :mod:`django.contrib.gis.db.backends.spatialite`
+
+Database Settings Backwards-Compatibility
+-----------------------------------------
+
+In :doc:`Django 1.2 </releases/1.2>`, the way
+to :ref:`specify databases <specifying-databases>` in your settings was changed.
+The old database settings format (e.g., the ``DATABASE_*`` settings)
+is backwards compatible with GeoDjango, and  will automatically use the
+appropriate spatial backend as long as :mod:`django.contrib.gis` is in
+your :setting:`INSTALLED_APPS`.  For example, if you have the following in
+your settings::
+
+    DATABASE_ENGINE='postgresql_psycopg2'
+
+    ...
+
+    INSTALLED_APPS = (
+      ...
+      'django.contrib.gis',
+      ...
+    )
+
+Then, :mod:`django.contrib.gis.db.backends.postgis` is automatically used as your
+spatial backend.
+
+.. _mysql-spatial-limitations:
+
+MySQL Spatial Limitations
+-------------------------
+
+MySQL's spatial extensions only support bounding box operations
+(what MySQL calls minimum bounding rectangles, or MBR).  Specifically,
+`MySQL does not conform to the OGC standard <http://dev.mysql.com/doc/refman/5.1/en/functions-that-test-spatial-relationships-between-geometries.html>`_:
+
+    Currently, MySQL does not implement these functions
+    [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``,
+    ``Touches``, ``Within``]
+    according to the specification.  Those that are implemented return
+    the same result as the corresponding MBR-based functions.
+
+In other words, while spatial lookups such as :lookup:`contains <gis-contains>`
+are available in GeoDjango when using MySQL, the results returned are really
+equivalent to what would be returned when using :lookup:`bbcontains`
+on a different spatial backend.
+
+.. warning::
+
+    True spatial indexes (R-trees) are only supported with
+    MyISAM tables on MySQL. [#fnmysqlidx]_ In other words, when using
+    MySQL spatial extensions you have to choose between fast spatial
+    lookups and the integrity of your data -- MyISAM tables do
+    not support transactions or foreign key constraints.
+
+Creating and Saving Geographic Models
+=====================================
+Here is an example of how to create a geometry object (assuming the ``Zipcode``
+model)::
+
+    >>> from zipcode.models import Zipcode
+    >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
+    >>> z.save()
+
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models::
+
+    >>> from django.contrib.gis.geos import GEOSGeometry
+    >>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
+    >>> z = Zipcode(code=77096, poly=poly)
+    >>> z.save()
+
+Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a
+different SRID value) than that of the field, then it will be implicitly
+transformed into the SRID of the model's field, using the spatial database's
+transform procedure::
+
+    >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084)  # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
+    >>> z = Zipcode(code=78212, poly=poly_3084)
+    >>> z.save()
+    >>> from django.db import connection
+    >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True)
+    INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
+
+Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT
+(Well Known Text [#fnwkt]_), HEXEWKB (PostGIS specific -- a WKB geometry in
+hexadecimal [#fnewkb]_), and GeoJSON [#fngeojson]_ (requires GDAL). Essentially,
+if the input is not a ``GEOSGeometry`` object, the geometry field will attempt to
+create a ``GEOSGeometry`` instance from the input.
+
+For more information creating :class:`~django.contrib.gis.geos.GEOSGeometry`
+objects, refer to the :ref:`GEOS tutorial <geos-tutorial>`.
+
+.. _spatial-lookups-intro:
+
+Spatial Lookups
+===============
+
+GeoDjango's lookup types may be used with any manager method like
+``filter()``, ``exclude()``, etc.  However, the lookup types unique to
+GeoDjango are only available on geometry fields.
+Filters on 'normal' fields (e.g. :class:`~django.db.models.CharField`)
+may be chained with those on geographic fields.  Thus, geographic queries
+take the following general form (assuming  the ``Zipcode`` model used in the
+:ref:`ref-gis-model-api`)::
+
+    >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
+    >>> qs = Zipcode.objects.exclude(...)
+
+For example::
+
+    >>> qs = Zipcode.objects.filter(poly__contains=pnt)
+
+In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>`
+is the spatial lookup type, and ``pnt`` is the parameter (which may be a
+:class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of
+GeoJSON , WKT, or HEXEWKB).
+
+A complete reference can be found in the :ref:`spatial lookup reference
+<spatial-lookups>`.
+
+.. note::
+
+    GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a
+    subclass of :class:`~django.db.models.QuerySet`.  The
+    :class:`GeoManager` instance attached to your model is what
+    enables use of :class:`GeoQuerySet`.
+
+.. _distance-queries:
+
+Distance Queries
+================
+
+Introduction
+------------
+Distance calculations with spatial data is tricky because, unfortunately,
+the Earth is not flat.  Some distance queries with fields in a geographic
+coordinate system may have to be expressed differently because of
+limitations in PostGIS.  Please see the :ref:`selecting-an-srid` section
+in the :ref:`ref-gis-model-api` documentation for more details.
+
+.. _distance-lookups-intro:
+
+Distance Lookups
+----------------
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+The following distance lookups are available:
+
+* :lookup:`distance_lt`
+* :lookup:`distance_lte`
+* :lookup:`distance_gt`
+* :lookup:`distance_gte`
+* :lookup:`dwithin`
+
+.. note::
+
+    For *measuring*, rather than querying on distances, use the
+    :meth:`GeoQuerySet.distance` method.
+
+Distance lookups take a tuple parameter comprising:
+
+#. A geometry to base calculations from; and
+#. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance.
+
+If a :class:`~django.contrib.gis.measure.Distance` object is used,
+it may be expressed in any units (the SQL generated will use units
+converted to those of the field); otherwise, numeric parameters are assumed
+to be in the units of the field.
+
+.. note::
+
+    For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere``
+    is used by default for calculating distances on geographic coordinate systems
+    (e.g., WGS84) -- which may only be called with point geometries [#fndistsphere14]_.
+    Thus, geographic distance lookups on traditional PostGIS geometry columns are
+    only allowed on :class:`PointField` model fields using a point for the
+    geometry parameter.
+
+.. note::
+
+    In PostGIS 1.5, ``ST_Distance_Sphere`` does *not* limit the geometry types
+    geographic distance queries are performed with. [#fndistsphere15]_  However,
+    these queries may take a long time, as great-circle distances must be
+    calculated on the fly for *every* row in the query.  This is because the
+    spatial index on traditional geometry fields cannot be used.
+
+    For much better performance on WGS84 distance queries, consider using
+    :ref:`geography columns <geography-type>` in your database instead because
+    they are able to use their spatial index in distance queries.
+    You can tell GeoDjango to use a geography column by setting ``geography=True``
+    in your field definition.
+
+For example, let's say we have a ``SouthTexasCity`` model (from the
+`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities
+in southern Texas::
+
+    from django.contrib.gis.db import models
+
+    class SouthTexasCity(models.Model):
+        name = models.CharField(max_length=30)
+        # A projected coordinate system (only valid for South Texas!)
+        # is used, units are in meters.
+        point = models.PointField(srid=32140)
+        objects = models.GeoManager()
+
+Then distance queries may be performed as follows::
+
+    >>> from django.contrib.gis.geos import *
+    >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
+    >>> from geoapp import SouthTexasCity
+    # Distances will be calculated from this point, which does not have to be projected.
+    >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
+    # If numeric parameter, units of field (meters in this case) are assumed.
+    >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
+    # Find all Cities within 7 km, > 20 miles away, and > 100 chains  away (an obscure unit)
+    >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
+    >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
+    >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
+
+__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
+
+.. _compatibility-table:
+
+Compatibility Tables
+====================
+
+.. _spatial-lookup-compatibility:
+
+Spatial Lookups
+---------------
+
+The following table provides a summary of what spatial lookups are available
+for each spatial database backend.
+
+=================================  =========  ========  ============ ==========
+Lookup Type                        PostGIS    Oracle    MySQL [#]_   SpatiaLite
+=================================  =========  ========  ============ ==========
+:lookup:`bbcontains`               X                    X            X
+:lookup:`bboverlaps`               X                    X            X
+:lookup:`contained`                X                    X            X
+:lookup:`contains <gis-contains>`  X          X         X            X
+:lookup:`contains_properly`        X
+:lookup:`coveredby`                X          X
+:lookup:`covers`                   X          X
+:lookup:`crosses`                  X                                 X
+:lookup:`disjoint`                 X          X         X            X
+:lookup:`distance_gt`              X          X                      X
+:lookup:`distance_gte`             X          X                      X
+:lookup:`distance_lt`              X          X                      X
+:lookup:`distance_lte`             X          X                      X
+:lookup:`dwithin`                  X          X
+:lookup:`equals`                   X          X         X            X
+:lookup:`exact`                    X          X         X            X
+:lookup:`intersects`               X          X         X            X
+:lookup:`overlaps`                 X          X         X            X
+:lookup:`relate`                   X          X                      X
+:lookup:`same_as`                  X          X         X            X
+:lookup:`touches`                  X          X         X            X
+:lookup:`within`                   X          X         X            X
+:lookup:`left`                     X
+:lookup:`right`                    X
+:lookup:`overlaps_left`            X
+:lookup:`overlaps_right`           X
+:lookup:`overlaps_above`           X
+:lookup:`overlaps_below`           X
+:lookup:`strictly_above`           X
+:lookup:`strictly_below`           X
+=================================  =========  ========  ============ ==========
+
+.. _geoqueryset-method-compatibility:
+
+``GeoQuerySet`` Methods
+-----------------------
+The following table provides a summary of what :class:`GeoQuerySet` methods
+are available on each spatial backend.  Please note that MySQL does not
+support any of these methods, and is thus excluded from the table.
+
+====================================  =======  ======  ==========
+Method                                PostGIS  Oracle  SpatiaLite
+====================================  =======  ======  ==========
+:meth:`GeoQuerySet.area`              X        X       X
+:meth:`GeoQuerySet.centroid`          X        X       X
+:meth:`GeoQuerySet.collect`           X
+:meth:`GeoQuerySet.difference`        X        X       X
+:meth:`GeoQuerySet.distance`          X        X       X
+:meth:`GeoQuerySet.envelope`          X                X
+:meth:`GeoQuerySet.extent`            X        X
+:meth:`GeoQuerySet.extent3d`          X
+:meth:`GeoQuerySet.force_rhr`         X
+:meth:`GeoQuerySet.geohash`           X
+:meth:`GeoQuerySet.geojson`           X
+:meth:`GeoQuerySet.gml`               X        X
+:meth:`GeoQuerySet.intersection`      X        X       X
+:meth:`GeoQuerySet.kml`               X
+:meth:`GeoQuerySet.length`            X        X       X
+:meth:`GeoQuerySet.make_line`         X
+:meth:`GeoQuerySet.mem_size`          X
+:meth:`GeoQuerySet.num_geom`          X        X       X
+:meth:`GeoQuerySet.num_points`        X        X       X
+:meth:`GeoQuerySet.perimeter`         X        X
+:meth:`GeoQuerySet.point_on_surface`  X        X       X
+:meth:`GeoQuerySet.reverse_geom`      X        X
+:meth:`GeoQuerySet.scale`             X                X
+:meth:`GeoQuerySet.snap_to_grid`      X
+:meth:`GeoQuerySet.svg`               X                X
+:meth:`GeoQuerySet.sym_difference`    X        X       X
+:meth:`GeoQuerySet.transform`         X        X       X
+:meth:`GeoQuerySet.translate`         X                X
+:meth:`GeoQuerySet.union`             X        X       X
+:meth:`GeoQuerySet.unionagg`          X        X       X
+====================================  =======  ======  ==========
+
+.. rubric:: Footnotes
+.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at  Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
+.. [#fnewkb] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2.
+.. [#fngeojson] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008).
+.. [#fndistsphere14] *See* `PostGIS 1.4 documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``.
+.. [#fndistsphere15] *See* `PostGIS 1.5 documentation <http://postgis.refractions.net/documentation/manual-1.5/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``.
+.. [#fnmysqlidx] *See* `Creating Spatial Indexes <http://dev.mysql.com/doc/refman/5.1/en/creating-spatial-indexes.html>`_
+   in the MySQL 5.1 Reference Manual:
+
+       For MyISAM tables, ``SPATIAL INDEX`` creates an R-tree index. For storage
+       engines that support nonspatial indexing of spatial columns, the engine
+       creates a B-tree index. A B-tree index on spatial values will be useful
+       for exact-value lookups, but not for range scans.
+
+.. [#] Refer :ref:`mysql-spatial-limitations` section for more details.
diff --git a/parts/django/docs/ref/contrib/gis/deployment.txt b/parts/django/docs/ref/contrib/gis/deployment.txt
new file mode 100644
index 0000000..035b23f
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/deployment.txt
@@ -0,0 +1,99 @@
+===================
+Deploying GeoDjango
+===================
+
+.. warning::
+
+    GeoDjango uses the GDAL geospatial library which is
+    not thread safe at this time.  Thus, it is *highly* recommended
+    to not use threading when deploying -- in other words, use a 
+    an appropriate configuration of Apache or the prefork method
+    when using FastCGI through another Web server.
+
+Apache
+======
+In this section there are some example ``VirtualHost`` directives for 
+when deploying using either ``mod_python`` or ``mod_wsgi``.  At this
+time, we recommend ``mod_wsgi``, as it is now officially recommended 
+way to deploy Django applications with Apache.  Moreover, if
+``mod_python`` is used, then a prefork version of Apache must also be
+used.  As long as ``mod_wsgi`` is configured correctly, it does not
+matter whether the version of Apache is prefork or worker.
+
+.. note::
+
+    The ``Alias`` and ``Directory`` configurations in the the examples
+    below use an example path to a system-wide installation folder of Django.  
+    Substitute in an appropriate location, if necessary, as it may be
+    different than the path on your system.
+
+``mod_wsgi``
+------------
+
+Example::
+
+    <VirtualHost *:80>
+      WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1
+      WSGIProcessGroup geodjango
+      WSGIScriptAlias / /home/geo/geodjango/world.wsgi
+  
+      Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
+      <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/">
+        Order allow,deny
+        Options Indexes
+        Allow from all
+        IndexOptions FancyIndexing
+      </Directory>
+    
+    </VirtualHost>
+
+.. warning::
+
+    If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then
+    Apache may crash when running your GeoDjango application.  Increase the 
+    number of ``processes`` instead.
+
+For more information, please consult Django's
+:doc:`mod_wsgi documentation </howto/deployment/modwsgi>`.
+
+``mod_python``
+--------------
+
+Example::
+
+    <VirtualHost *:80>
+    
+      <Location "/">
+        SetHandler mod_python
+        PythonHandler django.core.handlers.modpython
+        SetEnv DJANGO_SETTINGS_MODULE world.settings
+        PythonDebug On
+        PythonPath "['/var/www/apps'] + sys.path"
+      </Location>
+    
+      Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
+      <Location "/media">
+        SetHandler None
+      </Location>
+    
+    </VirtualHost>
+
+.. warning::
+
+   When using ``mod_python`` you *must* be using a prefork version of Apache, or
+   else your GeoDjango application may crash Apache.
+
+For more information, please consult Django's
+:doc:`mod_python documentation </howto/deployment/modpython>`.
+
+Lighttpd
+========
+
+FastCGI
+-------
+
+Nginx
+=====
+
+FastCGI
+-------
diff --git a/parts/django/docs/ref/contrib/gis/feeds.txt b/parts/django/docs/ref/contrib/gis/feeds.txt
new file mode 100644
index 0000000..7c3a2d0
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/feeds.txt
@@ -0,0 +1,95 @@
+================
+Geographic Feeds
+================
+
+.. module:: django.contrib.gis.feeds
+   :synopsis: GeoDjango's framework for generating spatial feeds.
+
+GeoDjango has its own :class:`Feed` subclass that may embed location information
+in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or
+`W3C Geo`_ standards.  Because GeoDjango's syndication API is a superset of
+Django's, please consult :doc:`Django's syndication documentation
+</ref/contrib/syndication>` for details on general usage.
+
+.. _W3C Geo: http://www.w3.org/2003/01/geo/
+
+__ http://georss.org/1.0#simple
+
+Example
+=======
+
+API Reference
+=============
+
+``Feed`` Subclass
+-----------------
+
+.. class:: Feed
+
+   In addition to methods provided by
+   the :class:`django.contrib.syndication.feeds.Feed`
+   base class, GeoDjango's ``Feed`` class provides
+   the following overrides.  Note that these overrides may be done in multiple ways::
+
+       from django.contrib.gis.feeds import Feed
+
+       class MyFeed(Feed):
+
+            # First, as a class attribute.
+            geometry = ...
+            item_geometry = ...
+
+            # Also a function with no arguments
+            def geometry(self):
+                ...
+
+            def item_geometry(self):
+                ...
+
+            # And as a function with a single argument
+            def geometry(self, obj):
+                ...
+
+            def item_geometry(self, item):
+                ...
+
+   .. method:: geometry(obj)
+
+   Takes the object returned by ``get_object()`` and returns the *feed's*
+   geometry.  Typically this is a ``GEOSGeometry`` instance, or can be a
+   tuple to represent a point or a box.  For example::
+
+       class ZipcodeFeed(Feed):
+
+           def geometry(self, obj):
+               # Can also return: `obj.poly`, and `obj.poly.centroid`.
+               return obj.poly.extent # tuple like: (X0, Y0, X1, Y1).
+
+   .. method:: item_geometry(item)
+
+   Set this to return the geometry for each *item* in the feed.  This
+   can be a ``GEOSGeometry`` instance, or a tuple that represents a
+   point coordinate or bounding box.  For example::
+
+       class ZipcodeFeed(Feed):
+
+           def item_geometry(self, obj):
+	       # Returns the polygon.
+               return obj.poly
+
+``SyndicationFeed`` Subclasses
+------------------------------
+
+The following :class:`django.utils.feedgenerator.SyndicationFeed` subclasses
+are available:
+
+.. class:: GeoRSSFeed
+
+.. class:: GeoAtom1Feed
+
+.. class:: W3CGeoFeed
+
+.. note::
+
+    `W3C Geo`_ formatted feeds only support
+    :class:`~django.contrib.gis.db.models.PointField` geometries.
diff --git a/parts/django/docs/ref/contrib/gis/gdal.txt b/parts/django/docs/ref/contrib/gis/gdal.txt
new file mode 100644
index 0000000..1ce21d9
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/gdal.txt
@@ -0,0 +1,1114 @@
+.. _ref-gdal:
+
+========
+GDAL API
+========
+
+.. module:: django.contrib.gis.gdal
+   :synopsis: GeoDjango's high-level interface to the GDAL library.
+
+`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary,
+and is a veritable "swiss army knife" of GIS data functionality.  A subset
+of GDAL is the `OGR`__ Simple Features Library, which specializes
+in reading and writing vector geographic data in a variety of standard
+formats.
+
+GeoDjango provides a high-level Python interface for some of the 
+capabilities of OGR, including the reading and coordinate transformation
+of vector spatial data.
+
+.. note::
+
+     Although the module is named ``gdal``, GeoDjango only supports
+     some of the capabilities of OGR.  Thus, none of GDAL's features
+     with respect to raster (image) data are supported at this time.
+   
+__ http://www.gdal.org/
+__ http://www.gdal.org/ogr/
+
+Overview
+========
+
+Sample Data
+-----------
+
+The GDAL/OGR tools described here are designed to help you read in
+your geospatial data, in order for most of them to be useful you have
+to have some data to work with.  If you're starting out and don't yet
+have any data of your own to use, GeoDjango comes with a number of
+simple data sets that you can use for testing.  This snippet will
+determine where these sample files are installed on your computer::
+
+    >>> import os
+    >>> import django.contrib.gis
+    >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__)
+    >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp')
+
+Vector Data Source Objects
+==========================
+
+``DataSource``
+--------------
+
+:class:`DataSource` is a wrapper for the OGR data source object that
+supports reading data from a variety of OGR-supported geospatial file
+formats and data sources using a simple, consistent interface.  Each
+data source is represented by a :class:`DataSource` object which contains
+one or more layers of data.  Each layer, represented by a :class:`Layer`
+object, contains some number of geographic features (:class:`Feature`),
+information about the type of features contained in that layer (e.g.
+points, polygons, etc.), as well as the names and types of any
+additional fields (:class:`Field`) of data that may be associated with
+each feature in that layer.
+
+.. class:: DataSource(ds_input)
+
+   The constructor for ``DataSource`` just a single parameter: the path of
+   the file you want to read.  However, OGR
+   also supports a variety of more complex data sources, including
+   databases, that may be accessed by passing a special name string instead
+   of a path.  For more information, see the `OGR Vector Formats`__
+   documentation.  The :attr:`name` property of a ``DataSource`` 
+   instance gives the OGR name of the underlying data source that it is
+   using.
+
+   Once you've created your ``DataSource``, you can find out how many 
+   layers of data it contains by accessing the :attr:`layer_count` property, 
+   or (equivalently) by using the ``len()`` function.  For information on 
+   accessing the layers of data themselves, see the next section::
+
+       >>> from django.contrib.gis.gdal import DataSource
+       >>> ds = DataSource(CITIES_PATH)
+       >>> ds.name                         # The exact filename may be different on your computer
+       '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp'
+       >>> ds.layer_count                  # This file only contains one layer
+       1
+
+   .. attribute:: layer_count
+
+   Returns the number of layers in the data source.
+
+   .. attribute:: name
+
+   Returns the name of the data source.
+
+__ http://www.gdal.org/ogr/ogr_formats.html
+
+``Layer``
+---------
+
+.. class:: Layer
+
+   ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object.
+   You never create a ``Layer`` object directly.  Instead, you retrieve
+   them from a :class:`DataSource` object, which is essentially a standard
+   Python container of ``Layer`` objects.  For example, you can access a
+   specific layer by its index (e.g. ``ds[0]`` to access the first
+   layer), or you can iterate over all the layers in the container in a
+   ``for`` loop.  The ``Layer`` itself acts as a container for geometric 
+   features.
+
+   Typically, all the features in a given layer have the same geometry type.
+   The :attr:`geom_type` property of a layer is an :class:`OGRGeomType`
+   that identifies the feature type.  We can use it to print out some basic
+   information about each layer in a :class:`DataSource`::
+
+       >>> for layer in ds:
+       ...     print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)
+       ...
+       Layer "cities": 3 Points
+
+   The example output is from the cities data source, loaded above, which
+   evidently contains one layer, called ``"cities"``, which contains three
+   point features.  For simplicity, the examples below assume that you've 
+   stored that layer in the variable ``layer``::
+
+       >>> layer = ds[0]
+
+   .. attribute:: name
+
+   Returns the name of this layer in the data source.
+
+       >>> layer.name
+       'cities'
+
+   .. attribute:: num_feat
+
+   Returns the number of features in the layer.  Same as ``len(layer)``::
+
+       >>> layer.num_feat
+       3
+
+   .. attribute:: geom_type
+
+   Returns the geometry type of the layer, as an :class:`OGRGeomType`
+   object::
+
+       >>> layer.geom_type.name
+       'Point'
+
+   .. attribute:: num_fields
+
+   Returns the number of fields in the layer, i.e the number of fields of
+   data associated with each feature in the layer::
+
+       >>> layer.num_fields
+       4
+
+   .. attribute:: fields
+
+   Returns a list of the names of each of the fields in this layer::
+
+       >>> layer.fields
+       ['Name', 'Population', 'Density', 'Created']
+
+   .. attribute field_types
+
+   Returns a list of the data types of each of the fields in this layer.
+   These are subclasses of ``Field``, discussed below::
+
+       >>> [ft.__name__ for ft in layer.field_types]
+       ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']
+ 
+   .. attribute:: field_widths
+
+   Returns a list of the maximum field widths for each of the fields in
+   this layer::
+
+      >>> layer.field_widths
+      [80, 11, 24, 10]
+
+   .. attribute:: field_precisions
+
+   Returns a list of the numeric precisions for each of the fields in
+   this layer.  This is meaningless (and set to zero) for non-numeric 
+   fields::
+
+       >>> layer.field_precisions
+       [0, 0, 15, 0]
+
+   .. attribute:: extent
+
+   Returns the spatial extent of this layer, as an :class:`Envelope` 
+   object::
+
+      >>> layer.extent.tuple
+      (-104.609252, 29.763374, -95.23506, 38.971823)
+
+   .. attribute:: srs
+
+   Property that returns the :class:`SpatialReference` associated
+   with this layer::
+
+       >>> print layer.srs
+       GEOGCS["GCS_WGS_1984",
+           DATUM["WGS_1984",
+               SPHEROID["WGS_1984",6378137,298.257223563]],
+           PRIMEM["Greenwich",0],
+           UNIT["Degree",0.017453292519943295]]
+
+   If the :class:`Layer` has no spatial reference information associated
+   with it, ``None`` is returned.
+
+   .. attribute:: spatial_filter
+
+   .. versionadded:: 1.2
+
+   Property that may be used to retrieve or set a spatial filter for this
+   layer.  A spatial filter can only be set with an :class:`OGRGeometry`
+   instance, a 4-tuple extent, or ``None``.  When set with something 
+   other than ``None``, only features that intersect the filter will be
+   returned when iterating over the layer::
+
+       >>> print layer.spatial_filter
+       None
+       >>> print len(layer)
+       3
+       >>> [feat.get('Name') for feat in layer]
+       ['Pueblo', 'Lawrence', 'Houston']
+       >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas
+       >>> layer.spatial_filter = ks_extent
+       >>> len(layer)
+       1
+       >>> [feat.get('Name') for feat in layer]
+       ['Lawrence']
+       >>> layer.spatial_filter = None
+       >>> len(layer)
+       3
+
+   .. method:: get_fields()
+
+   A method that returns a list of the values of a given field for each
+   feature in the layer::
+
+      >>> layer.get_fields('Name')
+      ['Pueblo', 'Lawrence', 'Houston']
+
+   .. method:: get_geoms([geos=False])
+
+   A method that returns a list containing the geometry of each feature
+   in the layer.  If the optional argument ``geos`` is set to ``True``
+   then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry`
+   objects. Otherwise, they are returned as :class:`OGRGeometry` objects::
+
+       >>> [pt.tuple for pt in layer.get_geoms()]
+       [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]
+
+   .. method:: test_capability(capability)
+
+   Returns a boolean indicating whether this layer supports the
+   given capability (a string).  Examples of valid capability strings
+   include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``,
+   ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``,
+   ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and 
+   ``'FastSetNextByIndex'``.
+   
+``Feature``
+-----------
+
+.. class:: Feature
+
+
+   ``Feature`` wraps an OGR feature.  You never create a ``Feature``
+   object directly.  Instead, you retrieve them from a :class:`Layer` object.
+   Each feature consists of a geometry and a set of fields containing
+   additional properties.  The geometry of a field is accessible via its
+   ``geom`` property, which returns an :class:`OGRGeometry` object.  A ``Feature``
+   behaves like a standard Python container for its fields, which it returns as
+   :class:`Field` objects: you can access a field directly by its index or name,
+   or you can iterate over a feature's fields, e.g. in a ``for`` loop.
+
+   .. attribute:: geom
+
+   Returns the geometry for this feature, as an ``OGRGeometry`` object::
+
+       >>> city.geom.tuple
+       (-104.609252, 38.255001)
+
+   .. attribute:: get
+
+   A method that returns the value of the given field (specified by name)
+   for this feature, **not** a ``Field`` wrapper object::
+
+       >>> city.get('Population')
+       102121
+
+   .. attribute:: geom_type
+
+   Returns the type of geometry for this feature, as an :class:`OGRGeomType`
+   object.  This will be the same for all features in a given layer, and
+   is equivalent to the :attr:`Layer.geom_type` property of the 
+   :class:`Layer`` object the feature came from.
+
+   .. attribute:: num_fields
+
+   Returns the number of fields of data associated with the feature.
+   This will be the same for all features in a given layer, and is
+   equivalent to the :attr:`Layer.num_fields` property of the 
+   :class:`Layer` object the feature came from.
+
+   .. attribute:: fields
+
+   Returns a list of the names of the fields of data associated with the
+   feature.  This will be the same for all features in a given layer, and
+   is equivalent to the :attr:`Layer.fields` property of the :class:`Layer`
+   object the feature came from.
+
+   .. attribute:: fid
+
+   Returns the feature identifier within the layer::
+
+       >>> city.fid
+       0
+
+   .. attribute:: layer_name
+
+   Returns the name of the :class:`Layer` that the feature came from.
+   This will be the same for all features in a given layer::
+
+       >>> city.layer_name
+       'cities'
+
+   .. attribute:: index
+
+   A method that returns the index of the given field name.  This will be
+   the same for all features in a given layer::
+
+       >>> city.index('Population')
+       1
+
+``Field``
+---------
+
+.. class:: Field
+
+   .. attribute:: name
+
+   Returns the name of this field::
+
+       >>> city['Name'].name
+       'Name'
+
+   .. attribute:: type
+
+   Returns the OGR type of this field, as an integer.  The
+   ``FIELD_CLASSES`` dictionary maps these values onto 
+   subclasses of ``Field``::
+
+       >>> city['Density'].type
+       2
+
+   .. attribute:: type_name
+
+   Returns a string with the name of the data type of this field::
+
+       >>> city['Name'].type_name
+       'String'
+
+   .. attribute:: value
+
+   Returns the value of this field.  The ``Field`` class itself 
+   returns the value as a string, but each subclass returns the 
+   value in the most appropriate form::
+
+       >>> city['Population'].value
+       102121
+
+   .. attribute:: width
+
+   Returns the width of this field::
+
+       >>> city['Name'].width
+       80
+
+   .. attribute:: precision
+
+   Returns the numeric precision of this field.  This is meaningless (and
+   set to zero) for non-numeric fields::
+
+       >>> city['Density'].precision
+       15
+
+   .. method:: as_double()
+
+   Returns the value of the field as a double (float)::
+
+       >>> city['Density'].as_double()
+       874.7
+
+   .. method:: as_int()
+
+   Returns the value of the field as an integer::
+
+       >>> city['Population'].as_int()
+       102121
+
+   .. method:: as_string()
+
+   Returns the value of the field as a string::
+
+       >>> city['Name'].as_string()
+       'Pueblo'
+
+   .. method:: as_datetime()
+
+   Returns the value of the field as a tuple of date and time components::
+
+       >>> city['Created'].as_datetime()
+       (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))
+
+``Driver``
+----------
+
+.. class:: Driver(dr_input)
+
+   The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver.
+
+   .. attribute:: driver_count
+
+   Returns the number of OGR vector drivers currently registered.
+
+
+OGR Geometries
+==============
+
+``OGRGeometry``
+---------------
+
+:class:`OGRGeometry` objects share similar functionality with 
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin
+wrappers around OGR's internal geometry representation.  Thus, 
+they allow for more efficient access to data when using :class:`DataSource`. 
+Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference
+systems and coordinate transformation::
+
+    >>> from django.contrib.gis.gdal import OGRGeometry
+    >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))')
+
+.. class:: OGRGeometry(geom_input[, srs=None])
+
+   This object is a wrapper for the `OGR Geometry`__ class.
+   These objects are instantiated directly from the given ``geom_input`` 
+   parameter, which may be a string containing WKT or HEX, a ``buffer``
+   containing WKB data, or an :class:`OGRGeomType` object. These objects
+   are also returned from the :class:`Feature.geom` attribute, when 
+   reading vector data from :class:`Layer` (which is in turn a part of
+   a :class:`DataSource`).
+
+   __ http://www.gdal.org/ogr/classOGRGeometry.html
+
+   .. classmethod:: from_bbox(bbox)
+
+   .. versionadded:: 1.1
+
+   Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple).
+
+   .. method:: __len__
+
+   Returns the number of points in a :class:`LineString`, the
+   number of rings in a :class:`Polygon`, or the number of geometries in a
+   :class:`GeometryCollection`. Not applicable to other geometry types.
+
+   .. method:: __iter__
+
+   Iterates over the points in a :class:`LineString`, the rings in a
+   :class:`Polygon`, or the geometries in a :class:`GeometryCollection`.
+   Not applicable to other geometry types.
+
+   .. method:: __getitem__
+
+   Returns the point at the specified index for a :class:`LineString`, the
+   interior ring at the specified index for a :class:`Polygon`, or the geometry
+   at the specified index in a :class:`GeometryCollection`.  Not applicable to
+   other geometry types.
+
+   .. attribute:: dimension
+
+   Returns the number of coordinated dimensions of the geometry, i.e. 0
+   for points, 1 for lines, and so forth::
+
+       >> polygon.dimension
+       2
+
+   .. attribute:: coord_dim
+
+   .. versionchanged:: 1.2
+
+   Returns or sets the coordinate dimension of this geometry.  For
+   example, the value would be 2 for two-dimensional geometries.
+
+   .. note::
+
+      Setting this property is only available in versions 1.2 and above.
+
+   .. attribute:: geom_count
+
+   Returns the number of elements in this geometry::
+
+       >>> polygon.geom_count
+       1
+
+   .. attribute:: point_count
+
+   Returns the number of points used to describe this geometry::
+
+      >>> polygon.point_count
+      4
+
+   .. attribute:: num_points
+
+   Alias for :attr:`point_count`.
+
+   .. attribute:: num_coords
+
+   Alias for :attr:`point_count`.
+
+   .. attribute:: geom_type
+
+   Returns the type of this geometry, as an :class:`OGRGeomType` object.
+
+   .. attribute:: geom_name
+
+   Returns the name of the type of this geometry::
+
+       >>> polygon.geom_name
+       'POLYGON'
+
+   .. attribute:: area
+
+   Returns the area of this geometry, or 0 for geometries that do not
+   contain an area::
+
+       >>> polygon.area
+       25.0
+
+   .. attribute:: envelope
+
+   Returns the envelope of this geometry, as an :class:`Envelope` object.
+
+   .. attribute:: extent
+
+   Returns the envelope of this geometry as a 4-tuple, instead of as an
+   :class:`Envelope` object::
+
+       >>> point.extent
+       (0.0, 0.0, 5.0, 5.0)
+
+   .. attribute:: srs
+
+   This property controls the spatial reference for this geometry, or
+   ``None`` if no spatial reference system has been assigned to it.
+   If assigned, accessing this property returns a :class:`SpatialReference`
+   object.  It may be set with another :class:`SpatialReference` object,
+   or any input that :class:`SpatialReference` accepts. Example::
+
+       >>> city.geom.srs.name
+       'GCS_WGS_1984'
+
+   .. attribute:: srid
+
+   Returns or sets the spatial reference identifier corresponding to 
+   :class:`SpatialReference` of this geometry.  Returns ``None`` if
+   there is no spatial reference information associated with this
+   geometry, or if an SRID cannot be determined.
+
+   .. attribute:: geos
+
+   Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object 
+   corresponding to this geometry.
+
+   .. attribute:: gml
+
+   Returns a string representation of this geometry in GML format::
+
+       >>> OGRGeometry('POINT(1 2)').gml
+       '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'
+
+   .. attribute:: hex
+
+   Returns a string representation of this geometry in HEX WKB format::
+
+       >>> OGRGeometry('POINT(1 2)').hex
+       '0101000000000000000000F03F0000000000000040'
+
+   .. attribute:: json
+
+   Returns a string representation of this geometry in JSON format::
+
+       >>> OGRGeometry('POINT(1 2)').json
+       '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'
+
+
+   .. attribute:: kml
+
+   .. versionadded:: 1.1
+
+   Returns a string representation of this geometry in KML format.
+
+   .. attribute:: wkb_size
+
+   Returns the size of the WKB buffer needed to hold a WKB representation
+   of this geometry::
+
+       >>> OGRGeometry('POINT(1 2)').wkb_size
+       21
+
+   .. attribute:: wkb
+
+   Returns a ``buffer`` containing a WKB representation of this geometry.
+
+   .. attribute:: wkt
+
+   Returns a string representation of this geometry in WKT format.
+
+   .. attribute:: ewkt
+
+   .. versionadded:: 1.2
+
+   Returns the EWKT representation of this geometry.
+
+   .. method:: clone()
+
+   Returns a new :class:`OGRGeometry` clone of this geometry object.
+
+   .. method:: close_rings()
+
+   If there are any rings within this geometry that have not been closed,
+   this routine will do so by adding the starting point to the end::
+
+       >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)')
+       >>> triangle.close_rings()
+       >>> triangle.wkt
+       'LINEARRING (0 0,0 1,1 0,0 0)'
+
+   .. method:: transform(coord_trans, clone=False)
+
+   Transforms this geometry to a different spatial reference system.  May
+   take a :class:`CoordTransform` object, a :class:`SpatialReference` object,
+   or any other input accepted by :class:`SpatialReference` (including
+   spatial reference WKT and PROJ.4 strings, or an integer SRID).
+   By default nothing is returned and the geometry is transformed in-place.
+   However, if the `clone` keyword is set to ``True`` then a transformed clone
+   of this geometry is returned instead.
+
+   .. method:: intersects(other)
+
+   Returns ``True`` if this geometry intersects the other, otherwise returns
+   ``False``.
+
+   .. method:: equals(other)
+
+   Returns ``True`` if this geometry is equivalent to the other, otherwise returns
+   ``False``.
+
+   .. method:: disjoint(other)
+
+   Returns ``True`` if this geometry is spatially disjoint to (i.e. does
+   not intersect) the other, otherwise returns ``False``.
+
+   .. method:: touches(other)
+
+   Returns ``True`` if this geometry touches the other, otherwise returns
+   ``False``.
+
+   .. method:: crosses(other)
+
+   Returns ``True`` if this geometry crosses the other, otherwise returns
+   ``False``.
+
+   .. method:: within(other)
+
+   Returns ``True`` if this geometry is contained within the other, otherwise returns
+   ``False``.
+
+   .. method:: contains(other)
+
+   Returns ``True`` if this geometry contains the other, otherwise returns
+   ``False``.
+
+   .. method:: overlaps(other)
+
+   Returns ``True`` if this geometry overlaps the other, otherwise returns
+   ``False``.
+
+   .. method:: boundary
+
+   The boundary of this geometry, as a new :class:`OGRGeometry` object.
+
+   .. attribute:: convex_hull
+
+   The smallest convex polygon that contains this geometry, as a new
+   :class:`OGRGeometry` object.
+
+   .. method:: difference
+
+   Returns the region consisting of the difference of this geometry and
+   the other, as a new :class:`OGRGeometry` object.
+
+   .. method:: intersection
+
+   Returns the region consisting of the intersection of this geometry and
+   the other, as a new :class:`OGRGeometry` object.
+
+   .. method:: sym_difference
+
+   Returns the region consisting of the symmetric difference of this
+   geometry and the other, as a new :class:`OGRGeometry` object.
+
+   .. method:: union
+
+   Returns the region consisting of the union of this geometry and
+   the other, as a new :class:`OGRGeometry` object.
+
+   .. attribute:: tuple
+
+   Returns the coordinates of a point geometry as a tuple, the
+   coordinates of a line geometry as a tuple of tuples, and so forth::
+
+       >>> OGRGeometry('POINT (1 2)').tuple
+       (1.0, 2.0)
+       >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple
+       ((1.0, 2.0), (3.0, 4.0))
+
+   .. attribute:: coords
+
+   An alias for :attr:`tuple`.
+
+.. class:: Point
+
+   .. attribute:: x
+
+   Returns the X coordinate of this point::
+
+       >>> OGRGeometry('POINT (1 2)').x
+       1.0
+
+   .. attribute:: y
+
+   Returns the Y coordinate of this point::
+
+       >>> OGRGeometry('POINT (1 2)').y
+       2.0
+
+   .. attribute:: z
+
+   Returns the Z coordinate of this point, or ``None`` if the
+   the point does not have a Z coordinate::
+
+       >>> OGRGeometry('POINT (1 2 3)').z
+       3.0
+
+.. class:: LineString
+
+   .. attribute:: x
+
+   Returns a list of X coordinates in this line::
+
+       >>> OGRGeometry('LINESTRING (1 2,3 4)').x
+       [1.0, 3.0]
+
+   .. attribute:: y
+
+   Returns a list of Y coordinates in this line::
+
+       >>> OGRGeometry('LINESTRING (1 2,3 4)').y
+       [2.0, 4.0]
+
+   .. attribute:: z
+
+   Returns a list of Z coordinates in this line, or ``None`` if the 
+   line does not have Z coordinates::
+ 
+       >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z
+       [3.0, 6.0]
+
+
+.. class:: Polygon
+
+   .. attribute:: shell
+
+   Returns the shell or exterior ring of this polygon, as a ``LinearRing``
+   geometry.
+
+   .. attribute:: exterior_ring
+
+   An alias for :attr:`shell`.
+
+   .. attribute:: centroid
+
+   Returns a :class:`Point` representing the centroid of this polygon.
+
+.. class:: GeometryCollection
+
+   .. method:: add(geom)
+
+   Adds a geometry to this geometry collection.  Not applicable to other
+   geometry types.
+
+
+``OGRGeomType``
+---------------
+
+.. class:: OGRGeomType(type_input)
+
+   This class allows for the representation of an OGR geometry type
+   in any of several ways::
+
+       >>> from django.contrib.gis.gdal import OGRGeomType
+       >>> gt1 = OGRGeomType(3)             # Using an integer for the type
+       >>> gt2 = OGRGeomType('Polygon')     # Using a string
+       >>> gt3 = OGRGeomType('POLYGON')     # It's case-insensitive
+       >>> print gt1 == 3, gt1 == 'Polygon' # Equivalence works w/non-OGRGeomType objects
+       True True
+
+   .. attribute:: name
+
+   Returns a short-hand string form of the OGR Geometry type::
+
+       >>> gt1.name
+       'Polygon'
+
+   .. attribute:: num
+
+   Returns the number corresponding to the OGR geometry type::
+
+       >>> gt1.num
+       3
+
+   .. attribute:: django
+
+   Returns the Django field type (a subclass of GeometryField) to use for
+   storing this OGR type, or ``None`` if there is no appropriate Django
+   type::
+
+       >>> gt1.django
+       'PolygonField'
+
+``Envelope``
+------------
+
+.. class:: Envelope(*args)
+
+   Represents an OGR Envelope structure that contains the
+   minimum and maximum X, Y coordinates for a rectangle bounding box.
+   The naming of the variables is compatible with the OGR Envelope
+   C structure.
+
+   .. attribute:: min_x
+
+   The value of the minimum X coordinate.
+
+   .. attribute:: min_y
+
+   The value of the maximum X coordinate.
+
+   .. attribute:: max_x
+
+   The value of the minimum Y coordinate.
+
+   .. attribute:: max_y
+
+   The value of the maximum Y coordinate.
+
+   .. attribute:: ur
+
+   The upper-right coordinate, as a tuple.
+
+   .. attribute:: ll
+
+   The lower-left coordinate, as a tuple.
+
+   .. attribute:: tuple
+
+   A tuple representing the envelope.
+
+   .. attribute:: wkt
+
+   A string representing this envelope as a polygon in WKT format.
+
+
+   .. method:: expand_to_include(self, *args)
+
+   .. versionadded:: 1.1
+
+Coordinate System Objects
+=========================
+
+``SpatialReference``
+--------------------
+
+.. class:: SpatialReference(srs_input)
+
+   Spatial reference objects are initialized on the given ``srs_input``,
+   which may be one of the following:
+ 
+   * OGC Well Known Text (WKT) (a string)
+   * EPSG code (integer or string)
+   * PROJ.4 string
+   * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``)
+
+   Example::
+
+       >>> wgs84 = SpatialReference('WGS84') # shorthand string
+       >>> wgs84 = SpatialReference(4326) # EPSG code
+       >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string
+       >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
+       >>> wgs84 = SpatialReference(proj4) # PROJ.4 string
+       >>> wgs84 = SpatialReference("""GEOGCS["WGS 84",
+       DATUM["WGS_1984",
+            SPHEROID["WGS 84",6378137,298.257223563,
+                AUTHORITY["EPSG","7030"]],
+            AUTHORITY["EPSG","6326"]],
+        PRIMEM["Greenwich",0,
+            AUTHORITY["EPSG","8901"]],
+        UNIT["degree",0.01745329251994328,
+            AUTHORITY["EPSG","9122"]],
+        AUTHORITY["EPSG","4326"]]""") # OGC WKT
+
+   .. method:: __getitem__(target)
+
+   Returns the value of the given string attribute node, ``None`` if the node
+   doesn't exist.  Can also take a tuple as a parameter, (target, child), 
+   where child is the index of the attribute in the WKT.  For example::
+
+       >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]')
+       >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326
+       >>> print srs['GEOGCS']
+       WGS 84
+       >>> print srs['DATUM']
+       WGS_1984
+       >>> print srs['AUTHORITY']
+       EPSG
+       >>> print srs['AUTHORITY', 1] # The authority value
+       4326
+       >>> print srs['TOWGS84', 4] # the fourth value in this wkt
+       0
+       >>> print srs['UNIT|AUTHORITY'] # For the units authority, have to use the pipe symbole.
+       EPSG
+       >>> print srs['UNIT|AUTHORITY', 1] # The authority value for the untis
+       9122
+
+   .. method:: attr_value(target, index=0)
+
+   The attribute value for the given target node (e.g. ``'PROJCS'``).
+   The index keyword specifies an index of the child node to return.
+
+   .. method:: auth_name(target)
+
+   Returns the authority name for the given string target node.
+
+   .. method:: auth_code(target)
+
+   Returns the authority code for the given string target node.
+
+   .. method:: clone()
+
+   Returns a clone of this spatial reference object.
+
+   .. method:: identify_epsg()
+
+   This method inspects the WKT of this SpatialReference, and will
+   add EPSG authority nodes where an EPSG identifier is applicable.
+
+   .. method:: from_esri()
+
+   Morphs this SpatialReference from ESRI's format to EPSG
+
+   .. method:: to_esri()
+
+   Morphs this SpatialReference to ESRI's format.
+
+   .. method:: validate()
+
+   Checks to see if the given spatial reference is valid, if not
+   an exception will be raised.
+
+   .. method:: import_epsg(epsg)
+
+   Import spatial reference from EPSG code.
+
+   .. method:: import_proj(proj)
+
+   Import spatial reference from PROJ.4 string.
+
+   .. method:: import_user_input(user_input)
+  
+   .. versionadded:: 1.1
+
+   .. method:: import_wkt(wkt)
+
+   Import spatial reference from WKT.
+
+   .. method:: import_xml(xml)
+
+   Import spatial reference from XML.
+
+   .. attribute:: name
+
+   Returns the name of this Spatial Reference.
+
+   .. attribute:: srid
+
+   Returns the SRID of top-level authority, or ``None`` if undefined.
+
+   .. attribute:: linear_name
+
+   Returns the name of the linear units.
+
+   .. attribute:: linear_units
+
+   Returns the value of the linear units.
+
+   .. attribute:: angular_name
+
+   Returns the name of the angular units."
+
+   .. attribute:: angular_units
+
+   Returns the value of the angular units.
+
+   .. attribute:: units
+
+   Returns a 2-tuple of the units value and the units name, 
+   and will automatically determines whether to return the linear
+   or angular units.
+
+   .. attribute:: ellisoid
+
+   Returns a tuple of the ellipsoid parameters for this spatial
+   reference: (semimajor axis, semiminor axis, and inverse flattening)
+
+   .. attribute:: semi_major
+
+   Returns the semi major axis of the ellipsoid for this spatial reference.
+
+   .. attribute:: semi_minor
+
+   Returns the semi minor axis of the ellipsoid for this spatial reference.
+
+   .. attribute:: inverse_flattening
+
+   Returns the inverse flattening of the ellipsoid for this spatial reference.
+
+   .. attribute:: geographic
+
+   Returns ``True`` if this spatial reference is geographic
+   (root node is ``GEOGCS``).
+
+   .. attribute:: local
+
+   Returns ``True`` if this spatial reference is local
+   (root node is ``LOCAL_CS``).
+
+   .. attribute:: projected
+
+   Returns ``True`` if this spatial reference is a projected coordinate
+   system (root node is ``PROJCS``).
+
+   .. attribute:: wkt
+
+   Returns the WKT representation of this spatial reference.
+
+   .. attribute:: pretty_wkt
+
+   Returns the 'pretty' representation of the WKT.
+
+   .. attribute:: proj
+
+   Returns the PROJ.4 representation for this spatial reference.
+
+   .. attribute:: proj4
+
+   Alias for :attr:`SpatialReference.proj`.
+
+   .. attribute:: xml
+
+   Returns the XML representation of this spatial reference.
+
+
+``CoordTransform``
+------------------
+
+.. class:: CoordTransform(source, target)
+
+Represents a coordinate system transform.  It is initialized with two 
+:class:`SpatialReference`, representing the source and target coordinate
+systems, respectively.  These objects should be used when performing
+the same coordinate transformation repeatedly on different geometries::
+
+    >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83'))
+    >>> for feat in layer:
+    ...     geom = feat.geom # getting clone of feature geometry
+    ...     geom.transform(ct) # transforming
+
+Settings
+========
+
+.. setting:: GDAL_LIBRARY_PATH
+
+GDAL_LIBRARY_PATH
+-----------------
+
+A string specifying the location of the GDAL library.  Typically,
+this setting is only used if the GDAL library is in a non-standard
+location (e.g., ``/home/john/lib/libgdal.so``).
diff --git a/parts/django/docs/ref/contrib/gis/geoip.txt b/parts/django/docs/ref/contrib/gis/geoip.txt
new file mode 100644
index 0000000..784d69e
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/geoip.txt
@@ -0,0 +1,223 @@
+.. _ref-geoip:
+
+======================
+Geolocation with GeoIP
+======================
+
+.. module:: django.contrib.gis.utils.geoip
+   :synopsis: High-level Python interface for MaxMind's GeoIP C library.
+
+.. currentmodule:: django.contrib.gis.utils
+
+The :class:`GeoIP` object is a ctypes wrapper for the
+`MaxMind GeoIP C API`__. [#]_  This interface is a BSD-licensed alternative
+to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.
+
+In order to perform IP-based geolocation, the :class:`GeoIP` object requires
+the GeoIP C libary and either the GeoIP `Country`__ or `City`__ 
+datasets in binary format (the CSV files will not work!).  These datasets may be 
+`downloaded from MaxMind`__.  Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz``
+and unzip them in a directory corresponding to what you set 
+``GEOIP_PATH`` with in your settings.  See the example and reference below
+for more details.
+
+__ http://www.maxmind.com/app/c
+__ http://www.maxmind.com/app/python
+__ http://www.maxmind.com/app/country
+__ http://www.maxmind.com/app/city
+__ http://www.maxmind.com/download/geoip/database/
+
+Example
+=======
+
+Assuming you have the GeoIP C library installed, here is an example of its
+usage::
+
+     >>> from django.contrib.gis.utils import GeoIP
+     >>> g = GeoIP()
+     >>> g.country('google.com')
+     {'country_code': 'US', 'country_name': 'United States'}
+     >>> g.city('72.14.207.99')
+     {'area_code': 650,
+     'city': 'Mountain View',
+     'country_code': 'US',
+     'country_code3': 'USA',
+     'country_name': 'United States',
+     'dma_code': 807,
+     'latitude': 37.419200897216797,
+     'longitude': -122.05740356445312,
+     'postal_code': '94043',
+     'region': 'CA'}
+     >>> g.lat_lon('salon.com')
+     (37.789798736572266, -122.39420318603516)
+     >>> g.lon_lat('uh.edu')
+     (-95.415199279785156, 29.77549934387207) 
+     >>> g.geos('24.124.1.80').wkt
+     'POINT (-95.2087020874023438 39.0392990112304688)'
+
+``GeoIP`` Settings
+==================
+
+.. setting:: GEOIP_PATH
+
+GEOIP_PATH
+----------
+
+A string specifying the directory where the GeoIP data files are
+located.  This setting is *required* unless manually specified
+with ``path`` keyword when initializing the :class:`GeoIP` object.
+
+.. setting:: GEOIP_LIBRARY_PATH
+
+GEOIP_LIBRARY_PATH
+------------------
+
+A string specifying the location of the GeoIP C library.  Typically,
+this setting is only used if the GeoIP C library is in a non-standard
+location (e.g., ``/home/sue/lib/libGeoIP.so``).
+
+.. setting:: GEOIP_COUNTRY
+
+GEOIP_COUNTRY
+-------------
+
+The basename to use for the GeoIP country data file.
+Defaults to ``'GeoIP.dat'``.
+
+.. setting:: GEOIP_CITY
+
+GEOIP_CITY
+----------
+
+The basename to use for the GeoIP city data file.
+Defaults to ``'GeoLiteCity.dat'``.
+
+``GeoIP`` API
+=============
+
+.. class:: GeoIP([path=None, cache=0, country=None, city=None])
+
+The ``GeoIP`` object does not require any parameters to use the default 
+settings.  However, at the very least the :setting:`GEOIP_PATH` setting
+should be set with the path of the location of your GeoIP data sets.  The 
+following intialization keywords may be used to customize any of the 
+defaults. 
+
+===================  =======================================================
+Keyword Arguments    Description
+===================  =======================================================
+``path``             Base directory to where GeoIP data is located or the 
+                     full path to where the city or country data files 
+                     (.dat) are located.  Assumes that both the city and 
+                     country data sets are located in this directory; 
+                     overrides the :setting:`GEOIP_PATH` settings attribute.
+
+``cache``            The cache settings when opening up the GeoIP datasets,
+                     and may be an integer in (0, 1, 2, 4) corresponding to
+                     the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``, 
+                     ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE`` 
+                     ``GeoIPOptions`` C API settings, respectively. 
+                     Defaults to 0 (``GEOIP_STANDARD``).
+ 
+``country``          The name of the GeoIP country data file.  Defaults
+                     to ``GeoIP.dat``.  Setting this keyword overrides the 
+                     :setting:`GEOIP_COUNTRY` settings attribute.
+
+``city``             The name of the GeoIP city data file.  Defaults to
+                     ``GeoLiteCity.dat``.  Setting this keyword overrides
+                     the :setting:`GEOIP_CITY` settings attribute.
+===================  =======================================================
+
+``GeoIP`` Methods
+=================
+
+Querying
+--------
+
+All the following querying routines may take either a string IP address
+or a fully qualified domain name (FQDN).  For example, both 
+``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query 
+parameters. 
+
+.. method:: GeoIP.city(query)
+
+Returns a dictionary of city information for the given query.  Some
+of the values in the dictionary may be undefined (``None``).
+
+.. method:: GeoIPcountry(query)
+
+Returns a dictionary with the country code and country for the given 
+query.
+
+.. method:: GeoIP.country_code(query)
+
+Returns only the country code corresponding to the query.
+
+.. method:: GeoIP.country_name(query)
+
+Returns only the country name corresponding to the query.
+
+Coordinate Retrieval
+--------------------
+
+.. method:: GeoIP.coords(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lon_lat(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lat_lon(query)
+
+Returns a coordinate tuple of (latitude, longitude),
+
+.. method:: GeoIP.geos(query)
+
+Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.
+
+Database Information
+--------------------
+
+.. attribute:: GeoIP.country_info
+
+This property returns information about the GeoIP country database.
+
+.. attribute:: GeoIP.city_info
+
+This property returns information about the GeoIP city database.
+
+.. attribute:: GeoIP.info
+
+This property returns information about all GeoIP databases (both city
+and country).
+
+GeoIP-Python API compatibility methods
+----------------------------------------
+
+These methods exist to ease compatibility with any code using MaxMind's 
+existing Python API.
+
+.. classmethod:: GeoIP.open(path, cache)
+
+This classmethod instantiates the GeoIP object from the given database path
+and given cache setting.
+
+.. method:: GeoIP.region_by_addr(query)
+
+.. method:: GeoIP.region_by_name(query)
+
+.. method:: GeoIP.record_by_addr(query)
+
+.. method:: GeoIP.record_by_name(query)
+
+.. method:: GeoIP.country_code_by_addr(query)
+
+.. method:: GeoIP.country_code_by_name(query)
+
+.. method:: GeoIP.country_name_by_addr(query)
+
+.. method:: GeoIP.country_name_by_name(query)
+
+.. rubric:: Footnotes
+.. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts.
diff --git a/parts/django/docs/ref/contrib/gis/geoquerysets.txt b/parts/django/docs/ref/contrib/gis/geoquerysets.txt
new file mode 100644
index 0000000..69f0c02
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/geoquerysets.txt
@@ -0,0 +1,1256 @@
+.. _ref-geoquerysets:
+
+=========================
+GeoQuerySet API Reference
+=========================
+
+.. currentmodule:: django.contrib.gis.db.models
+
+.. class:: GeoQuerySet([model=None])
+
+
+.. _spatial-lookups:
+
+Spatial Lookups
+===============
+
+Just like when using the the :ref:`queryset-api`, interaction
+with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`.
+Instead of the regular Django :ref:`field-lookups`, the
+spatial lookups in this section are available for :class:`GeometryField`.
+
+For an introduction, see the :ref:`spatial lookups introduction
+<spatial-lookups-intro>`.  For an overview of what lookups are
+compatible with a particular spatial backend, refer to the
+:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`.
+
+.. fieldlookup:: bbcontains
+
+bbcontains
+----------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box completely contains the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__bbcontains=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``poly ~ geom``
+MySQL       ``MBRContains(poly, geom)``
+SpatiaLite  ``MbrContains(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: bboverlaps
+
+bboverlaps
+----------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box overlaps the lookup geometry's
+bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__bboverlaps=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``poly && geom``
+MySQL       ``MBROverlaps(poly, geom)``
+SpatiaLite  ``MbrOverlaps(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: contained
+
+contained
+---------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box is completely contained by the
+lookup geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__contained=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``poly @ geom``
+MySQL       ``MBRWithin(poly, geom)``
+SpatiaLite  ``MbrWithin(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: gis-contains
+
+contains
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially contains the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__contains=geom)
+
+==========  ============================
+Backend     SQL Equivalent
+==========  ============================
+PostGIS     ``ST_Contains(poly, geom)``
+Oracle      ``SDO_CONTAINS(poly, geom)``
+MySQL       ``MBRContains(poly, geom)``
+SpatiaLite  ``Contains(poly, geom)``
+==========  ============================
+
+.. fieldlookup:: contains_properly
+
+contains_properly
+-----------------
+
+.. versionadded:: 1.2
+
+*Availability*: PostGIS
+
+Returns true if the lookup geometry intersects the interior of the
+geometry field, but not the boundary (or exterior). [#fncontainsproperly]_
+
+.. note::
+
+    Requires PostGIS 1.4 and above.
+
+Example::
+
+    Zipcode.objects.filter(poly__contains_properly=geom)
+
+==========  ===================================
+Backend     SQL Equivalent
+==========  ===================================
+PostGIS     ``ST_ContainsProperly(poly, geom)``
+==========  ===================================
+
+.. fieldlookup:: coveredby
+
+coveredby
+---------
+
+*Availability*: PostGIS, Oracle
+
+Tests if no point in the geometry field is outside the lookup geometry.
+[#fncovers]_
+
+Example::
+
+    Zipcode.objects.filter(poly__coveredby=geom)
+
+==========  =============================
+Backend     SQL Equivalent
+==========  =============================
+PostGIS     ``ST_CoveredBy(poly, geom)``
+Oracle      ``SDO_COVEREDBY(poly, geom)``
+==========  =============================
+
+.. fieldlookup:: covers
+
+covers
+------
+
+*Availability*: PostGIS, Oracle
+
+Tests if no point in the lookup geometry is outside the geometry field.
+[#fncovers]_
+
+Example::
+
+    Zipcode.objects.filter(poly__covers=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``ST_Covers(poly, geom)``
+Oracle      ``SDO_COVERS(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: crosses
+
+crosses
+-------
+
+*Availability*: PostGIS, SpatiaLite
+
+Tests if the geometry field spatially crosses the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__crosses=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``ST_Crosses(poly, geom)``
+SpatiaLite  ``Crosses(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: disjoint
+
+disjoint
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field is spatially disjoint from the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__disjoint=geom)
+
+==========  =================================================
+Backend     SQL Equivalent
+==========  =================================================
+PostGIS     ``ST_Disjoint(poly, geom)``
+Oracle      ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)``
+MySQL       ``MBRDisjoint(poly, geom)``
+SpatiaLite  ``Disjoint(poly, geom)``
+==========  =================================================
+
+equals
+------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: exact
+.. fieldlookup:: same_as
+
+exact, same_as
+--------------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: intersects
+
+intersects
+----------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially intersects the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__intersects=geom)
+
+==========  =================================================
+Backend     SQL Equivalent
+==========  =================================================
+PostGIS     ``ST_Intersects(poly, geom)``
+Oracle      ``SDO_OVERLAPBDYINTERSECT(poly, geom)``
+MySQL       ``MBRIntersects(poly, geom)``
+SpatiaLite  ``Intersects(poly, geom)``
+==========  =================================================
+
+.. fieldlookup:: overlaps
+
+overlaps
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: relate
+
+relate
+------
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Tests if the geometry field is spatially related to the the lookup geometry by
+the values given in the given pattern.  This lookup requires a tuple parameter,
+``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend:
+
+PostGIS & SpatiaLite
+~~~~~~~~~~~~~~~~~~~~
+On these spatial backends the intersection pattern is a string comprising
+nine characters, which  define intersections between  the interior, boundary,
+and exterior of the geometry field and the lookup geometry.
+The intersection pattern matrix may only use the following characters:
+``1``, ``2``, ``T``, ``F``, or ``*``.  This lookup type allows users to "fine tune"
+a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_
+
+Example::
+
+    # A tuple lookup parameter is used to specify the geometry and
+    # the intersection pattern (the pattern here is for 'contains').
+    Zipcode.objects.filter(poly__relate(geom, 'T*T***FF*'))
+
+PostGIS SQL equivalent::
+
+    SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
+
+SpatiaLite SQL equivalent::
+
+    SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')
+
+Oracle
+~~~~~~
+
+Here the relation pattern is compreised at least one of the nine relation
+strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
+``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and
+``ANYINTERACT``.   Multiple strings may be combined with the logical Boolean
+operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_  The relation
+strings are case-insensitive.
+
+Example::
+
+    Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
+
+Oracle SQL equivalent::
+
+    SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
+
+.. fieldlookup:: touches
+
+touches
+-------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially touches the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__touches=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``ST_Touches(poly, geom)``
+MySQL       ``MBRTouches(poly, geom)``
+Oracle      ``SDO_TOUCH(poly, geom)``
+SpatiaLite  ``Touches(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: within
+
+within
+------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field is spatially within the lookup geometry.
+
+Example::
+
+    Zipcode.objects.filter(poly__within=geom)
+
+==========  ==========================
+Backend     SQL Equivalent
+==========  ==========================
+PostGIS     ``ST_Within(poly, geom)``
+MySQL       ``MBRWithin(poly, geom)``
+Oracle      ``SDO_INSIDE(poly, geom)``
+SpatiaLite  ``Within(poly, geom)``
+==========  ==========================
+
+.. fieldlookup:: left
+
+left
+----
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly to the left of the
+lookup geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__left=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly << geom
+
+.. fieldlookup:: right
+
+right
+-----
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly to the right of the
+lookup geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__right=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly >> geom
+
+.. fieldlookup:: overlaps_left
+
+overlaps_left
+-------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is to the left of the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__overlaps_left=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly &< geom
+
+
+.. fieldlookup:: overlaps_right
+
+overlaps_right
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is to the right of the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__overlaps_right=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly &> geom
+
+.. fieldlookup:: overlaps_above
+
+overlaps_above
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is above the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__overlaps_above=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly |&> geom
+
+.. fieldlookup:: overlaps_below
+
+overlaps_below
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is below the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__overlaps_below=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly &<| geom
+
+.. fieldlookup:: strictly_above
+
+strictly_above
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly above the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__strictly_above=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly |>> geom
+
+.. fieldlookup:: strictly_below
+
+strictly_below
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly above the lookup
+geometry's bounding box.
+
+Example::
+
+    Zipcode.objects.filter(poly__strictly_above=geom)
+
+PostGIS equivalent::
+
+    SELECT ... WHERE poly |>> geom
+
+
+.. _distance-lookups:
+
+Distance Lookups
+================
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+For an overview on performing distance queries, please refer to
+the :ref:`distance queries introduction <distance-queries>`.
+
+Distance lookups take the following form::
+
+    <field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid'])
+
+The value passed into a distance lookup is a tuple; the first two
+values are mandatory, and are the geometry to calculate distances to,
+and a distance value (either a number in units of the field or a
+:class:`~django.contrib.gis.measure.Distance` object).  On every
+distance lookup but :lookup:`dwithin`, an optional
+third element, ``'spheroid'``, may be included to tell GeoDjango
+to use the more accurate spheroid distance calculation functions on
+fields with a geodetic coordinate system (e.g., ``ST_Distance_Spheroid``
+would be used instead of ``ST_Distance_Sphere``).
+
+.. fieldlookup:: distance_gt
+
+distance_gt
+-----------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is greater than the given distance value.
+
+Example::
+
+    Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
+
+==========  ===============================================
+Backend     SQL Equivalent
+==========  ===============================================
+PostGIS     ``ST_Distance(poly, geom) > 5``
+Oracle      ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5``
+SpatiaLite  ``Distance(poly, geom) > 5``
+==========  ===============================================
+
+.. fieldlookup:: distance_gte
+
+distance_gte
+------------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is greater than or equal to the given distance value.
+
+Example::
+
+    Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
+
+==========  ================================================
+Backend     SQL Equivalent
+==========  ================================================
+PostGIS     ``ST_Distance(poly, geom) >= 5``
+Oracle      ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5``
+SpatiaLite  ``Distance(poly, geom) >= 5``
+==========  ================================================
+
+.. fieldlookup:: distance_lt
+
+distance_lt
+-----------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is less than the given distance value.
+
+Example::
+
+    Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
+
+==========  ===============================================
+Backend     SQL Equivalent
+==========  ===============================================
+PostGIS     ``ST_Distance(poly, geom) < 5``
+Oracle      ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5``
+SpatiaLite  ``Distance(poly, geom) < 5``
+==========  ===============================================
+
+.. fieldlookup:: distance_lte
+
+distance_lte
+------------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is less than or equal to the given distance value.
+
+Example::
+
+    Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
+
+==========  ================================================
+Backend     SQL Equivalent
+==========  ================================================
+PostGIS     ``ST_Distance(poly, geom) <= 5``
+Oracle      ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5``
+SpatiaLite  ``Distance(poly, geom) <= 5``
+==========  ================================================
+
+.. fieldlookup:: dwithin
+
+dwithin
+-------
+
+Returns models where the distance to the geometry field from the
+lookup geometry are within the given distance from one another.
+
+Example::
+
+    Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
+
+==========  ======================================
+Backend     SQL Equivalent
+==========  ======================================
+PostGIS     ``ST_DWithin(poly, geom, 5)``
+Oracle      ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
+==========  ======================================
+
+.. note::
+
+    This lookup is not available on SpatiaLite.
+
+.. fieldlookup:: equals
+
+
+``GeoQuerySet`` Methods
+=======================
+
+``GeoQuerySet`` methods specify that a spatial operation be performed
+on each patial operation on each geographic
+field in the queryset and store its output in a new attribute on the model
+(which is generally the name of the ``GeoQuerySet`` method).
+
+There are also aggregate ``GeoQuerySet`` methods which return a single value
+instead of a queryset.  This section will describe the API and availability
+of every ``GeoQuerySet`` method available in GeoDjango.
+
+.. note::
+
+    What methods are available depend on your spatial backend.  See
+    the :ref:`compatibility table <geoqueryset-method-compatibility>`
+    for more details.
+
+With a few exceptions, the following keyword arguments may be used with all
+``GeoQuerySet`` methods:
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``field_name``         By default, ``GeoQuerySet`` methods use the first
+                       geographic field encountered in the model.  This
+                       keyword should be used to specify another
+                       geographic field (e.g., ``field_name='point2'``)
+                       when there are multiple geographic fields in a model.
+
+                       On PostGIS, the ``field_name`` keyword may also be
+                       used on geometry fields in models that are related
+                       via a ``ForeignKey`` relation (e.g.,
+                       ``field_name='related__point'``).
+
+``model_att``          By default, ``GeoQuerySet`` methods typically attach
+                       their output in an attribute with the same name as
+                       the ``GeoQuerySet`` method.  Setting this keyword
+                       with the desired attribute name will override this
+                       default behavior.  For example,
+                       ``qs = Zipcode.objects.centroid(model_att='c')`` will
+                       attach the centroid of the ``Zipcode`` geometry field
+                       in a ``c`` attribute on every model rather than in a
+                       ``centroid`` attribute.
+
+                       This keyword is required if
+                       a method name clashes with an existing
+                       ``GeoQuerySet`` method -- if you wanted to use the
+                       ``area()`` method on model with a ``PolygonField``
+		       named ``area``, for example.
+=====================  =====================================================
+
+Measurement
+-----------
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+``area``
+~~~~~~~~
+
+.. method:: GeoQuerySet.area(**kwargs)
+
+Returns the area of the geographic field in an ``area`` attribute on
+each element of this GeoQuerySet.
+
+``distance``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.distance(geom, **kwargs)
+
+This method takes a geometry as a parameter, and attaches a ``distance``
+attribute to every model in the returned queryset that contains the
+distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry.
+
+In the following example (taken from the `GeoDjango distance tests`__),
+the distance from the `Tasmanian`__ city of Hobart to every other
+:class:`PointField` in the ``AustraliaCity`` queryset is calculated::
+
+    >>> pnt = AustraliaCity.objects.get(name='Hobart').point
+    >>> for city in AustraliaCity.objects.distance(pnt): print city.name, city.distance
+    Wollongong 990071.220408 m
+    Shellharbour 972804.613941 m
+    Thirroul 1002334.36351 m
+    Mittagong 975691.632637 m
+    Batemans Bay 834342.185561 m
+    Canberra 598140.268959 m
+    Melbourne 575337.765042 m
+    Sydney 1056978.87363 m
+    Hobart 0.0 m
+    Adelaide 1162031.83522 m
+    Hillsdale 1049200.46122 m
+
+.. note::
+
+    Because the ``distance`` attribute is a
+    :class:`~django.contrib.gis.measure.Distance` object, you can easily express
+    the value in the units of your choice.  For example, ``city.distance.mi`` is
+    the distance value in miles and ``city.distance.km`` is the distance value
+    in kilometers.  See the :ref:`ref-measure` for usage details and the list of
+    :ref:`supported_units`.
+
+__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
+__ http://en.wikipedia.org/wiki/Tasmania
+
+``length``
+~~~~~~~~~~
+
+.. method:: GeoQuerySet.length(**kwargs)
+
+Returns the length of the geometry field in a ``length`` attribute
+(a :class:`~django.contrib.gis.measure.Distance` object) on each model in
+the queryset.
+
+``perimeter``
+~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.perimeter(**kwargs)
+
+Returns the perimeter of the geometry field in a ``perimeter`` attribute
+(a :class:`~django.contrib.gis.measure.Distance` object) on each model in
+the queryset.
+
+Geometry Relationships
+----------------------
+
+The following methods take no arguments, and attach geometry objects
+each element of the :class:`GeoQuerySet` that is the result of relationship
+function evaluated on the the geometry field.
+
+``centroid``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.centroid(**kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Returns the ``centroid`` value for the geographic field in a ``centroid``
+attribute on each element of the ``GeoQuerySet``.
+
+``envelope``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.envelope(**kwargs)
+
+*Availability*: PostGIS, SpatiaLite
+
+Returns a geometry representing the bounding box of the geometry field in
+an ``envelope`` attribute on each element of the ``GeoQuerySet``.
+
+``point_on_surface``
+~~~~~~~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.point_on_surface(**kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Returns a Point geometry guaranteed to lie on the surface of the
+geometry field in a ``point_on_surface`` attribute on each element
+of the queryset; otherwise sets with None.
+
+Geometry Editors
+----------------
+
+``force_rhr``
+~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.force_rhr(**kwargs)
+
+.. versionadded:: 1.2
+
+*Availability*: PostGIS
+
+Returns a modified version of the polygon/multipolygon in which all
+of the vertices follow the Right-Hand-Rule, and attaches as a
+``force_rhr`` attribute on each element of the queryset.
+
+``reverse_geom``
+~~~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.reverse_geom(**kwargs)
+
+.. versionadded:: 1.2
+
+*Availability*: PostGIS, Oracle
+
+Reverse the coordinate order of the geometry field, and attaches as a
+``reverse`` attribute on each element of the queryset.
+
+``scale``
+~~~~~~~~~
+
+.. method:: GeoQuerySet.scale(x, y, z=0.0, **kwargs)
+
+*Availability*: PostGIS, SpatiaLite
+
+``snap_to_grid``
+~~~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.snap_to_grid(*args, **kwargs)
+
+.. versionadded:: 1.1
+
+Snap all points of the input geometry to the grid.  How the
+geometry is snapped to the grid depends on how many numeric
+(either float, integer, or long) arguments are given.
+
+===================  =====================================================
+Number of Arguments  Description
+===================  =====================================================
+1                    A single size to snap bot the X and Y grids to.
+2                    X and Y sizes to snap the grid to.
+4                    X, Y sizes and the corresponding X, Y origins.
+===================  =====================================================
+
+``transform``
+~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.transform(srid=4326, **kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+The ``transform`` method transforms the geometry field of a model to the spatial
+reference system specified by the ``srid`` parameter.  If no ``srid`` is given,
+then 4326 (WGS84) is used by default.
+
+.. note::
+
+    Unlike other ``GeoQuerySet`` methods, ``transform`` stores its output
+    "in-place".  In other words, no new attribute for the transformed
+    geometry is placed on the models.
+
+.. note::
+
+    What spatial reference system an integer SRID corresponds to may depend on
+    the spatial database used.  In other words, the SRID numbers used for Oracle
+    are not necessarily the same as those used by PostGIS.
+
+Example::
+
+    >>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
+    >>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
+    >>> print qs[0].poly.srid
+    32140
+    >>> print qs[0].poly
+    POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
+
+``translate``
+~~~~~~~~~~~~~
+.. method:: GeoQuerySet.translate(x, y, z=0.0, **kwargs)
+
+*Availability*: PostGIS, SpatiaLite
+
+Translates the geometry field to a new location using the given numeric
+parameters as offsets.
+
+Geometry Operations
+-------------------
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+The following methods all take a geometry as a parameter and attach a geometry
+to each element of the ``GeoQuerySet`` that is the result of the operation.
+
+``difference``
+~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.difference(geom)
+
+Returns the spatial difference of the geographic field with the given
+geometry in a ``difference`` attribute on each element of the
+``GeoQuerySet``.
+
+
+``intersection``
+~~~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.intersection(geom)
+
+Returns the spatial intersection of the geographic field with the
+given geometry in an ``intersection`` attribute on each element of the
+``GeoQuerySet``.
+
+``sym_difference``
+~~~~~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.sym_difference(geom)
+
+Returns the symmetric difference of the geographic field with the
+given geometry in a ``sym_difference`` attribute on each element of the
+``GeoQuerySet``.
+
+``union``
+~~~~~~~~~
+
+.. method:: GeoQuerySet.union(geom)
+
+Returns the union of the geographic field with the given
+geometry in an ``union`` attribute on each element of the
+``GeoQuerySet``.
+
+Geometry Output
+---------------
+
+The following ``GeoQuerySet`` methods will return an attribute that has the value
+of the geometry field in each model converted to the requested output format.
+
+``geohash``
+~~~~~~~~~~~
+
+.. method:: GeoQuerySet.geohash(preceision=20, **kwargs)
+
+.. versionadded:: 1.2
+
+Attaches a ``geohash`` attribute to every model the the queryset
+containing the `GeoHash`__ representation of the geometry.
+
+__ http://geohash.org/
+
+``geojson``
+~~~~~~~~~~~
+
+.. method:: GeoQuerySet.geojson(**kwargs)
+
+.. versionadded:: 1.1
+
+*Availability*: PostGIS
+
+Attaches a ``geojson`` attribute to every model in the queryset that contains the
+`GeoJSON`__ representation of the geometry.
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``precision``          It may be used to specify the number of significant
+                       digits for the coordinates in the GeoJSON
+                       representation -- the default value is 8.
+
+``crs``                Set this to ``True`` if you want the coordinate
+                       reference system to be included in the returned
+                       GeoJSON.
+
+``bbox``               Set this to ``True`` if you want the bounding box
+                       to be included in the returned GeoJSON.
+=====================  =====================================================
+
+__ http://geojson.org/
+
+``gml``
+~~~~~~~
+
+.. method:: GeoQuerySet.gml(**kwargs)
+
+*Availability*: PostGIS, Oracle
+
+Attaches a ``gml`` attribute to every model in the queryset that contains the
+`Geographic Markup Language (GML)`__ representation of the geometry.
+
+Example::
+
+    >>> qs = Zipcode.objects.all().gml()
+    >>> print qs[0].gml
+    <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``precision``          This keyword is for PostGIS only.  It may be used
+                       to specify the number of significant digits for the
+                       coordinates in the GML representation -- the default
+                       value is 8.
+
+``version``            This keyword is for PostGIS only.  It may be used to
+                       specify the GML version used, and may only be values
+                       of 2 or 3.  The default value is 2.
+=====================  =====================================================
+
+__ http://en.wikipedia.org/wiki/Geography_Markup_Language
+
+``kml``
+~~~~~~~
+
+.. method:: GeoQuerySet.kml(**kwargs)
+
+*Availability*: PostGIS
+
+Attaches a ``kml`` attribute to every model in the queryset that contains the
+`Keyhole Markup Language (KML)`__ representation of the geometry fields. It
+should be noted that the contents of the KML are transformed to WGS84 if
+necessary.
+
+Example::
+
+    >>> qs = Zipcode.objects.all().kml()
+    >>> print qs[0].kml
+    <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``precision``          This keyword may be used to specify the number of
+                       significant digits for the coordinates in the KML
+                       representation -- the default value is 8.
+=====================  =====================================================
+
+__ http://code.google.com/apis/kml/documentation/
+
+``svg``
+~~~~~~~
+
+.. method:: GeoQuerySet.svg(**kwargs)
+
+*Availability*: PostGIS, SpatiaLite
+
+Attaches a ``svg`` attribute to every model in the queryset that contains
+the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields.
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``relative``           If set to ``True``, the path data will be implemented
+                       in terms of relative moves.  Defaults to ``False``,
+		       meaning that absolute moves are used instead.
+
+``precision``          This keyword may be used to specify the number of
+                       significant digits for the coordinates in the SVG
+                       representation -- the default value is 8.
+=====================  =====================================================
+
+__ http://www.w3.org/Graphics/SVG/
+
+Miscellaneous
+-------------
+
+``mem_size``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.mem_size(**kwargs)
+
+*Availability*: PostGIS
+
+Returns the memory size (number of bytes) that the geometry field takes
+in a ``mem_size`` attribute  on each element of the ``GeoQuerySet``.
+
+``num_geom``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.num_geom(**kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Returns the number of geometries in a ``num_geom`` attribute on
+each element of the ``GeoQuerySet`` if the geometry field is a
+collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field);
+otherwise sets with ``None``.
+
+``num_points``
+~~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.num_points(**kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Returns the number of points in the first linestring in the
+geometry field in a ``num_points`` attribute on each element of
+the ``GeoQuerySet``; otherwise sets with ``None``.
+
+Spatial Aggregates
+==================
+.. versionadded:: 1.1
+
+Aggregate Methods
+-----------------
+
+``collect``
+~~~~~~~~~~~
+
+.. method:: GeoQuerySet.collect(**kwargs)
+
+.. versionadded:: 1.1
+
+*Availability*: PostGIS
+
+Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
+column.  This is analagous to a simplified version of the :meth:`GeoQuerySet.unionagg` method,
+except it can be several orders of magnitude faster than peforming a union because
+it simply rolls up geometries into a collection or multi object, not caring about
+dissolving boundaries.
+
+``extent``
+~~~~~~~~~~
+
+.. method:: GeoQuerySet.extent(**kwargs)
+
+*Availability*: PostGIS, Oracle
+
+Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the
+lower left coordinate and the upper right coordinate.
+
+Example::
+
+    >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
+    >>> print qs.extent()
+    (-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
+
+``extent3d``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.extent3d(**kwargs)
+
+.. versionadded:: 1.2
+
+*Availability*: PostGIS
+
+Returns the 3D extent of the ``GeoQuerySet`` as a six-tuple, comprising
+the lower left coordinate and upper right coordinate.
+
+Example::
+
+    >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
+    >>> print qs.extent3d()
+    (-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
+
+``make_line``
+~~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.make_line(**kwargs)
+
+*Availability*: PostGIS
+
+Returns a ``LineString`` constructed from the point field geometries in the
+``GeoQuerySet``.  Currently, ordering the queryset has no effect.
+
+Example::
+
+     >>> print City.objects.filter(name__in=('Houston', 'Dallas')).make_line()
+     LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
+
+``unionagg``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.unionagg(**kwargs)
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+This method returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object
+comprising the union of every geometry in the queryset.  Please note that
+use of ``unionagg`` is processor intensive and may take a significant amount
+of time on large querysets.
+
+.. note::
+
+    If the computation time for using this method is too expensive,
+    consider using :meth:`GeoQuerySet.collect` instead.
+
+Example::
+
+    >>> u = Zipcode.objects.unionagg() # This may take a long time.
+    >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach.
+
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``tolerance``          This keyword is for Oracle only.  It is for the
+                       tolerance value used by the ``SDOAGGRTYPE``
+                       procedure; the  `Oracle documentation`__ has more
+                       details.
+=====================  =====================================================
+
+__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
+
+Aggregate Functions
+-------------------
+
+Example::
+
+    >>> from django.contrib.gis.db.models import Extent, Union
+    >>> WorldBorders.objects.aggregate(Extent('mpoly'), Union('mpoly'))
+
+``Collect``
+~~~~~~~~~~~
+
+.. class:: Collect(geo_field)
+
+Returns the same as the :meth:`GeoQuerySet.collect` aggregate method.
+
+``Extent``
+~~~~~~~~~~
+.. class:: Extent(geo_field)
+
+
+Returns the same as the :meth:`GeoQuerySet.extent` aggregate method.
+
+``Extent3D``
+~~~~~~~~~~~~
+
+.. class:: Extent3D(geo_field)
+
+.. versionadded:: 1.2
+
+Returns the same as the :meth:`GeoQuerySet.extent3d` aggregate method.
+
+``MakeLine``
+~~~~~~~~~~~~
+
+.. class:: MakeLine(geo_field)
+
+Returns the same as the :meth:`GeoQuerySet.make_line` aggregate method.
+
+``Union``
+~~~~~~~~~
+
+.. class:: Union(geo_field)
+
+Returns the same as the :meth:`GeoQuerySet.union` aggregate method.
+
+.. rubric:: Footnotes
+.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
+.. [#fnsdorelate] *See* `SDO_RELATE documentation <http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_, from Ch. 11 of the Oracle Spatial User's Guide and Manual.
+.. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer).
+.. [#fncontainsproperly] Refer to the PostGIS ``ST_ContainsProperly`` `documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_ContainsProperly.html>`_ for more details.
diff --git a/parts/django/docs/ref/contrib/gis/geos.txt b/parts/django/docs/ref/contrib/gis/geos.txt
new file mode 100644
index 0000000..06a88a8
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/geos.txt
@@ -0,0 +1,911 @@
+.. _ref-geos:
+
+========
+GEOS API
+========
+
+.. module:: django.contrib.gis.geos
+   :synopsis: GeoDjango's high-level interface to the GEOS library.
+
+Background
+==========
+
+What is GEOS?
+-------------
+
+`GEOS`__ stands for **G**\ eometry **E**\ ngine - **O**\ pen **S**\ ource,
+and is a C++ library, ported from the  `Java Topology Suite`__.  GEOS
+implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions
+and spatial operators. GEOS, now an OSGeo project, was initially developed and
+maintained by `Refractions Research`__ of Victoria, Canada.
+
+__ http://trac.osgeo.org/geos/
+__ http://sourceforge.net/projects/jts-topo-suite/
+__ http://www.opengeospatial.org/standards/sfs
+__ http://www.refractions.net/
+
+Features
+--------
+
+GeoDjango implements a high-level Python wrapper for the GEOS library, its
+features include:
+
+* A BSD-licensed interface to the GEOS geometry routines, implemented purely
+  in Python using ``ctypes``.
+* Loosely-coupled to GeoDjango.  For example, :class:`GEOSGeometry` objects
+  may be used outside of a django project/application.  In other words, 
+  no need to have ``DJANGO_SETTINGS_MODULE`` set or use a database, etc.
+* Mutability: :class:`GEOSGeometry` objects may be modified.
+* Cross-platform and tested; compatible with Windows, Linux, Solaris, and Mac 
+  OS X platforms.
+
+.. _geos-tutorial:
+
+Tutorial
+========
+
+This section contains a brief introduction and tutorial to using 
+:class:`GEOSGeometry` objects.
+
+Creating a Geometry
+-------------------
+
+:class:`GEOSGeometry` objects may be created in a few ways.  The first is
+to simply instantiate the object on some spatial input -- the following
+are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON::
+
+    >>> from django.contrib.gis.geos import GEOSGeometry
+    >>> pnt = GEOSGeometry('POINT(5 23)') # WKT
+    >>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX
+    >>> pnt = GEOSGeometry(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
+    >>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON
+
+Another option is to use the constructor for the specific geometry type
+that you wish to create.  For example, a :class:`Point` object may be
+created by passing in the X and Y coordinates into its constructor::
+
+    >>> from django.contrib.gis.geos import Point
+    >>> pnt = Point(5, 23)
+
+Finally, there are :func:`fromstr` and :func:`fromfile` factory methods, which
+return a :class:`GEOSGeometry` object from an input string or a file::
+
+    >>> from django.contrib.gis.geos import fromstr, fromfile
+    >>> pnt = fromstr('POINT(5 23)')
+    >>> pnt = fromfile('/path/to/pnt.wkt')
+    >>> pnt = fromfile(open('/path/to/pnt.wkt'))
+
+Geometries are Pythonic 
+-----------------------
+:class:`GEOSGeometry` objects are 'Pythonic', in other words components may
+be accessed, modified, and iterated over using standard Python conventions.
+For example, you can iterate over the coordinates in a :class:`Point`::
+
+    >>> pnt = Point(5, 23)
+    >>> [coord for coord in pnt]
+    [5.0, 23.0]
+
+With any geometry object, the :attr:`GEOSGeometry.coords` property
+may be used to get the geometry coordinates as a Python tuple::
+
+    >>> pnt.coords
+    (5.0, 23.0)
+
+You can get/set geometry components using standard Python indexing
+techniques.  However, what is returned depends on the geometry type
+of the object.  For example, indexing on a :class:`LineString`
+returns a coordinate tuple::
+
+    >>> from django.contrib.gis.geos import LineString
+    >>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
+    >>> line[0]
+    (0.0, 0.0)
+    >>> line[-2]
+    (50.0, 0.0)
+
+Whereas indexing on a :class:`Polygon` will return the ring
+(a :class:`LinearRing` object) corresponding to the index::
+
+    >>> from django.contrib.gis.geos import Polygon
+    >>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) )
+    >>> poly[0]
+    <LinearRing object at 0x1044395b0>
+    >>> poly[0][-2] # second-to-last coordinate of external ring
+    (50.0, 0.0)
+
+In addition, coordinates/components of the geometry may added or modified,
+just like a Python list::
+
+    >>> line[0] = (1.0, 1.0)
+    >>> line.pop()
+    (0.0, 0.0)
+    >>> line.append((1.0, 1.0))
+    >>> line.coords
+    ((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))
+
+Geometry Objects
+================
+
+``GEOSGeometry``
+----------------
+
+.. class:: GEOSGeometry(geo_input[, srid=None])
+
+  :param geo_input: Geometry input value
+  :type geo_input: string or buffer
+  :param srid: spatial reference identifier
+  :type srid: integer
+
+This is the base class for all GEOS geometry objects.  It initializes on the
+given ``geo_input`` argument, and then assumes the proper geometry subclass
+(e.g., ``GEOSGeometry('POINT(1 1)')`` will create a :class:`Point` object).
+
+The following input formats, along with their corresponding Python types,
+are accepted:
+
+=============  ======================
+Format         Input Type
+=============  ======================
+WKT / EWKT     ``str`` or ``unicode`` 
+HEX / HEXEWKB  ``str`` or ``unicode``
+WKB / EWKB     ``buffer``
+GeoJSON        ``str`` or ``unicode``
+=============  ======================
+
+Properties
+~~~~~~~~~~
+
+.. attribute:: GEOSGeometry.coords
+
+Returns the coordinates of the geometry as a tuple.
+
+.. attribute:: GEOSGeometry.empty
+
+Returns whether or not the set of points in the geometry is empty. 
+
+.. attribute:: GEOSGeometry.geom_type
+
+Returns a string corresponding to the type of geometry.  For example::
+
+    >>> pnt = GEOSGeometry('POINT(5 23)')
+    >>> pnt.geom_type
+    'Point'
+
+.. attribute:: GEOSGeometry.geom_typeid
+
+Returns the GEOS geometry type identification number.  The following table
+shows the value for each geometry type:
+
+===========================  ========
+Geometry                     ID
+===========================  ========
+:class:`Point`               0
+:class:`LineString`          1
+:class:`LinearRing`          2
+:class:`Polygon`             3
+:class:`MultiPoint`          4
+:class:`MultiLineString`     5
+:class:`MultiPolygon`        6
+:class:`GeometryCollection`  7
+===========================  ========
+
+.. attribute:: GEOSGeometry.num_coords
+
+Returns the number of coordinates in the geometry.
+
+.. attribute:: GEOSGeometry.num_geom
+
+Returns the number of geometries in this geometry.  In other words, will
+return 1 on anything but geometry collections.
+
+.. attribute:: GEOSGeometry.hasz
+
+Returns a boolean indicating whether the geometry is three-dimensional.
+
+.. attribute:: GEOSGeometry.ring
+
+Returns a boolean indicating whether the geometry is a ``LinearRing``.
+
+.. attribute:: GEOSGeometry.simple
+
+Returns a boolean indicating whether the geometry is 'simple'. A geometry
+is simple if and only if it does not intersect itself (except at boundary
+points).  For example, a :class:`LineString` object is not simple if it
+intersects itself. Thus, :class:`LinearRing` and :class`Polygon` objects
+are always simple because they do cannot intersect themselves, by
+definition.
+
+.. attribute:: GEOSGeometry.valid
+
+Returns a boolean indicating whether the geometry is valid.
+
+.. attribute:: GEOSGeometry.srid
+
+Property that may be used to retrieve or set the SRID associated with the
+geometry.  For example::
+
+    >>> pnt = Point(5, 23)
+    >>> print pnt.srid
+    None
+    >>> pnt.srid = 4326
+    >>> pnt.srid
+    4326
+
+Output Properties
+~~~~~~~~~~~~~~~~~
+
+The properties in this section export the :class:`GEOSGeometry` object into
+a different.  This output may be in the form of a string, buffer, or even
+another object.
+
+.. attribute:: GEOSGeometry.ewkt
+
+Returns the "extended" Well-Known Text of the geometry.  This representation
+is specific to PostGIS and is a super set of the OGC WKT standard. [#fnogc]_
+Essentially the SRID is prepended to the WKT representation, for example 
+``SRID=4326;POINT(5 23)``. 
+
+.. note::
+
+   The output from this property does not include the 3dm, 3dz, and 4d 
+   information that PostGIS supports in its EWKT representations.
+
+.. attribute:: GEOSGeometry.hex
+
+Returns the WKB of this Geometry in hexadecimal form.  Please note
+that the SRID and Z values are not included in this representation
+because it is not a part of the OGC specification (use the 
+:attr:`GEOSGeometry.hexewkb` property instead).
+
+.. attribute:: GEOSGeometry.hexewkb
+
+.. versionadded:: 1.2
+
+Returns the EWKB of this Geometry in hexadecimal form.  This is an 
+extension of the WKB specification that includes SRID and Z values 
+that are a part of this geometry.
+
+.. note::
+
+   GEOS 3.1 is *required* if you want valid 3D HEXEWKB.
+
+.. attribute:: GEOSGeometry.json
+
+Returns the GeoJSON representation of the geometry.
+
+.. note::
+
+    Requires GDAL.
+
+.. attribute:: GEOSGeometry.geojson
+
+Alias for :attr:`GEOSGeometry.json`.
+
+.. attribute:: GEOSGeometry.kml
+
+Returns a `KML`__ (Keyhole Markup Language) representation of the
+geometry.  This should only be used for geometries with an SRID of 
+4326 (WGS84), but this restriction is not enforced.
+
+.. attribute:: GEOSGeometry.ogr
+
+Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object 
+correspondg to the GEOS geometry.
+
+.. note::
+
+    Requires GDAL.
+
+.. _wkb:
+
+.. attribute:: GEOSGeometry.wkb
+
+Returns the WKB (Well-Known Binary) representation of this Geometry
+as a Python buffer.  SRID and Z values are not included, use the
+:attr:`GEOSGeometry.ewkb` property instead.
+
+.. _ewkb:
+
+.. attribute:: GEOSGeometry.ewkb
+
+.. versionadded:: 1.2
+
+Return the EWKB representation of this Geometry as a Python buffer.
+This is an extension of the WKB specification that includes any SRID
+and Z values that are a part of this geometry.
+
+.. note::
+
+   GEOS 3.1 is *required* if you want valid 3D EWKB.
+
+.. attribute:: GEOSGeometry.wkt
+
+Returns the Well-Known Text of the geometry (an OGC standard).
+
+__ http://code.google.com/apis/kml/documentation/
+
+Spatial Predicate Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All of the following spatial predicate methods take another
+:class:`GEOSGeometry` instance (``other``) as a parameter, and
+return a boolean.
+
+.. method:: GEOSGeometry.contains(other)
+
+Returns ``True`` if :meth:`GEOSGeometry.within` is ``False``.
+
+.. method:: GEOSGeometry.crosses(other)
+
+Returns ``True`` if the DE-9IM intersection matrix for the two Geometries
+is ``T*T******`` (for a point and a curve,a point and an area or a line 
+and an area) ``0********`` (for two curves).
+
+.. method:: GEOSGeometry.disjoint(other)
+
+Returns ``True`` if the DE-9IM intersection matrix for the two geometries
+is ``FF*FF****``.
+
+.. method:: GEOSGeometry.equals(other)
+
+Returns ``True`` if the DE-9IM intersection matrix for the two geometries 
+is ``T*F**FFF*``.
+
+.. method:: GEOSGeometry.equals_exact(other, tolerance=0)
+
+Returns true if the two geometries are exactly equal, up to a
+specified tolerance.  The ``tolerance`` value should be a floating
+point number representing the error tolerance in the comparison, e.g.,
+``poly1.equals_exact(poly2, 0.001)`` will compare equality to within
+one thousandth of a unit.
+
+.. method:: GEOSGeometry.intersects(other)
+
+Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``.
+
+.. method:: GEOSGeometry.overlaps(other)
+
+Returns true if the DE-9IM intersection matrix for the two geometries
+is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**``
+(for two curves).
+
+.. method:: GEOSGeometry.relate_pattern(other, pattern)
+
+Returns ``True`` if the elements in the DE-9IM intersection matrix 
+for this geometry and the other matches the given ``pattern`` -- 
+a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}.
+
+.. method:: GEOSGeometry.touches(other)
+
+Returns ``True`` if the DE-9IM intersection matrix for the two geometries
+is ``FT*******``, ``F**T*****`` or ``F***T****``.
+
+.. method:: GEOSGeometry.within(other)
+
+Returns ``True`` if the DE-9IM intersection matrix for the two geometries
+is ``T*F**F***``.
+
+Topological Methods
+~~~~~~~~~~~~~~~~~~~
+
+.. method:: GEOSGeometry.buffer(width, quadsegs=8)
+
+Returns a :class:`GEOSGeometry` that represents all points whose distance
+from this geometry is less than or equal to the given ``width``. The optional 
+``quadsegs`` keyword sets the number of segments used to approximate a 
+quarter circle (defaults is 8).
+
+.. method:: GEOSGeometry.difference(other)
+
+Returns a :class:`GEOSGeometry` representing the points making up this
+geometry that do not make up other.
+
+.. method:: GEOSGeometry:intersection(other)
+
+Returns a :class:`GEOSGeometry` representing the points shared by this
+geometry and other.
+
+.. method:: GEOSGeometry.relate(other)
+
+Returns the DE-9IM intersection matrix (a string) representing the
+topological relationship between this geometry and the other.
+
+.. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False)
+
+Returns a new :class:`GEOSGeometry`, simplified using the Douglas-Peucker
+algorithm to the specified tolerance.  A higher tolerance value implies
+less points in the output.  If no tolerance is tolerance provided,
+it defaults to 0.
+
+By default, this function does not preserve topology - e.g., 
+:class:`Polygon` objects can be split, collapsed into lines or disappear.
+:class:`Polygon` holes can be created or disappear, and lines can cross.
+By specifying ``preserve_topology=True``, the result will have the same
+dimension and number of components as the input, however, this is 
+significantly slower.   
+
+.. method:: GEOSGeometry.sym_difference(other)
+
+Returns a :class:`GEOSGeometry` combining the points in this geometry 
+not in other, and the points in other not in this geometry.
+
+.. method:: GEOSGeometry.union(other)
+
+Returns a :class:`GEOSGeometry` representing all the points in this 
+geometry and the other.
+
+Topological Properties
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: GEOSGeometry.boundary
+
+Returns the boundary as a newly allocated Geometry object.
+
+.. attribute:: GEOSGeometry.centroid
+
+Returns a :class:`Point` object representing the geometric center of
+the geometry.  The point is not guaranteed to be on the interior
+of the geometry.
+
+.. attribute:: GEOSGeometry.convex_hull
+
+Returns the smallest :class:`Polygon` that contains all the points in
+the geometry.
+
+.. attribute:: GEOSGeometry.envelope
+
+Returns a :class:`Polygon` that represents the bounding envelope of
+this geometry.
+
+.. attribute:: GEOSGeometry.point_on_surface
+
+Computes and returns a :class:`Point` guaranteed to be on the interior
+of this geometry.
+
+Other Properties & Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: GEOSGeometry.area
+
+This property returns the area of the Geometry.
+
+.. attribute:: GEOSGeometry.extent
+
+This property returns the extent of this geometry as a 4-tuple, 
+consisting of (xmin, ymin, xmax, ymax).
+
+.. method:: GEOSGeometry.clone()
+
+This method returns a :class:`GEOSGeometry` that is a clone of the original.
+
+.. method:: GEOSGeometry.distance(geom)
+
+Returns the distance between the closest points on this geometry and the given
+``geom`` (another :class:`GEOSGeometry` object).
+
+.. note::
+
+    GEOS distance calculations are  linear -- in other words, GEOS does not
+    perform a spherical calculation even if the SRID specifies a geographic 
+    coordinate system.
+
+.. attribute:: GEOSGeometry.length
+
+Returns the length of this geometry (e.g., 0 for a :class:`Point`, 
+the length of a :class:`LineString`, or the circumference of 
+a :class:`Polygon`).
+
+.. attribute:: GEOSGeometry.prepared
+
+.. versionadded:: 1.1
+
+.. note::
+
+    Support for prepared geometries requires GEOS 3.1.
+
+Returns a GEOS ``PreparedGeometry`` for the contents of this geometry.  
+``PreparedGeometry`` objects are optimized for the contains, intersects,
+and covers operations.  Refer to the :ref:`prepared-geometries` documentation
+for more information.
+
+.. attribute:: GEOSGeometry.srs
+
+Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object
+corresponding to the SRID of the geometry or ``None``.
+
+.. note::
+
+    Requires GDAL.
+
+.. method:: transform(ct, clone=False)
+
+Transforms the geometry according to the given coordinate transformation paramter
+(``ct``), which may be an integer SRID, spatial reference WKT string,
+a PROJ.4 string, a :class:`~django.contrib.gis.gdal.SpatialReference` object, or a 
+:class:`~django.contrib.gis.gdal.CoordTransform` object. By default, the geometry
+is transformed in-place and nothing is returned. However if the ``clone`` keyword
+is set, then the geometry is not modified and a transformed clone of the geometry
+is returned instead.
+
+.. note::
+
+    Requires GDAL.
+
+``Point``
+---------
+
+.. class:: Point(x, y, z=None, srid=None)
+
+   ``Point`` objects are instantiated using arguments that represent
+   the component coordinates of the point or with a single sequence
+   coordinates.  For example, the following are equivalent::
+
+       >>> pnt = Point(5, 23)
+       >>> pnt = Point([5, 23])
+
+``LineString``
+--------------
+
+.. class:: LineString(*args, **kwargs)
+
+   ``LineString`` objects are instantiated using arguments that are
+   either a sequence of coordinates or :class:`Point` objects.
+   For example, the following are equivalent::
+
+       >>> ls = LineString((0, 0), (1, 1))
+       >>> ls = LineString(Point(0, 0), Point(1, 1))
+
+   In addition, ``LineString`` objects may also be created by passing
+   in a single sequence of coordinate or :class:`Point` objects::
+
+       >>> ls = LineString( ((0, 0), (1, 1)) )
+       >>> ls = LineString( [Point(0, 0), Point(1, 1)] )
+
+``LinearRing``
+--------------
+
+.. class:: LinearRing(*args, **kwargs)
+
+   ``LinearRing`` objects are constructed in the exact same way as
+   :class:`LineString` objects, however the coordinates must be
+   *closed*, in other words, the first coordinates must be the
+   same as the last coordinates.  For example::
+
+       >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))
+
+   Notice that ``(0, 0)`` is the first and last coordinate -- if
+   they were not equal, an error would be raised.
+
+``Polygon``
+-----------
+
+.. class:: Polygon(*args, **kwargs)
+
+   ``Polygon`` objects may be instantiated by passing in one or
+   more parameters that represent the rings of the polygon.  The
+   parameters must either be :class:`LinearRing` instances, or
+   a sequence that may be used to construct a :class:`LinearRing`::
+
+       >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
+       >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
+       >>> poly = Polygon(ext_coords, int_coords)
+       >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))
+
+   .. classmethod:: from_bbox(bbox)
+
+   .. versionadded:: 1.1
+
+   Returns a polygon object from the given bounding-box, a 4-tuple
+   comprising (xmin, ymin, xmax, ymax).
+
+   .. attribute:: num_interior_rings
+
+   Returns the number of interior rings in this geometry.
+
+Geometry Collections
+====================
+
+``MultiPoint``
+--------------
+
+.. class:: MultiPoint(*args, **kwargs)
+
+   ``MultiPoint`` objects may be instantiated by passing in one
+   or more :class:`Point` objects as arguments, or a single
+   sequence of :class:`Point` objects::
+
+       >>> mp = MultiPoint(Point(0, 0), Point(1, 1))
+       >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) )
+
+``MultiLineString``
+-------------------
+
+.. class:: MultiLineString(*args, **kwargs)
+
+   ``MultiLineString`` objects may be instantiated by passing in one
+   or more :class:`LineString` objects as arguments, or a single
+   sequence of :class:`LineString` objects::
+
+       >>> ls1 = LineString((0, 0), (1, 1))
+       >>> ls2 = LineString((2, 2), (3, 3))
+       >>> mls = MultiLineString(ls1, ls2)
+       >>> mls = MultiLineString([ls1, ls2])
+
+   .. attribute:: merged
+
+   .. versionadded:: 1.1
+
+   Returns a :class:`LineString` representing the line merge of
+   all the components in this ``MultiLineString``.
+       
+
+``MultiPolygon``
+----------------
+
+.. class:: MultiPolygon(*args, **kwargs)
+
+   ``MultiPolygon`` objects may be instantiated by passing one or
+   more :class:`Polygon` objects as arguments, or a single sequence
+   of :class:`Polygon` objects::
+
+       >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) )
+       >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) )
+       >>> mp = MultiPolygon(p1, p2)
+       >>> mp = MultiPolygon([p1, p2])
+
+   .. attribute:: cascaded_union
+
+   .. versionadded:: 1.1
+
+   Returns a :class:`Polygon` that is the union of all of the component
+   polygons in this collection.  The algorithm employed is significantly
+   more efficient (faster) than trying to union the geometries together
+   individually. [#fncascadedunion]_
+
+   .. note::
+
+       GEOS 3.1 is *required* to peform cascaded unions.
+
+``GeometryCollection``
+----------------------
+
+.. class:: GeometryCollection(*args, **kwargs)
+
+   ``GeometryCollection`` objects may be instantiated by passing in
+   one or more other :class:`GEOSGeometry` as arguments, or a single
+   sequence of :class:`GEOSGeometry` objects::
+
+       >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) )
+       >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
+       >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))
+
+.. _prepared-geometries:
+
+Prepared Geometries
+===================
+
+.. versionadded: 1.1
+
+In order to obtain a prepared geometry, just access the
+:attr:`GEOSGeometry.prepared` property.  Once you have a
+``PreparedGeometry`` instance its spatial predicate methods, listed below,
+may be used with other ``GEOSGeometry`` objects.  An operation with a prepared
+geometry can be orders of magnitude faster -- the more complex the geometry 
+that is prepared, the larger the speedup in the operation.  For more information,
+please consult the `GEOS wiki page on prepared geometries <http://trac.osgeo.org/geos/wiki/PreparedGeometry>`_.
+
+.. note::
+
+   GEOS 3.1 is *required* in order to use prepared geometries.
+
+For example::
+
+    >>> from django.contrib.gis.geos import Point, Polygon
+    >>> poly = Polygon.from_bbox((0, 0, 5, 5))
+    >>> prep_poly = poly.prepared
+    >>> prep_poly.contains(Point(2.5, 2.5))
+    True
+
+``PreparedGeometry``
+--------------------
+
+.. class:: PreparedGeometry
+
+  All methods on ``PreparedGeometry`` take an ``other`` argument, which
+  must be a :class:`GEOSGeometry` instance.
+
+  .. method:: contains(other)
+
+  .. method:: contains_properly(other)
+
+  .. method:: covers(other)
+
+  .. method:: intersects(other)
+
+Geometry Factories
+==================
+
+.. function:: fromfile(file_h)
+
+   :param file_h: input file that contains spatial data
+   :type file_h: a Python ``file`` object or a string path to the file
+   :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file
+
+Example::
+
+    >>> from django.contrib.gis.geos import fromfile
+    >>> g = fromfile('/home/bob/geom.wkt')
+
+.. function:: fromstr(string, [,srid=None])
+
+   :param string: string that contains spatial data
+   :type string: string
+   :param srid: spatial reference identifier
+   :type srid: integer
+   :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string
+
+Example::
+
+    >>> from django.contrib.gis.geos import fromstr
+    >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)
+
+I/O Objects
+===========
+
+.. versionadded: 1.1
+
+Reader Objects
+--------------
+
+The reader I/O classes simply return a :class:`GEOSGeometry` instance from the
+WKB and/or WKT input given to their ``read(geom)`` method.
+
+.. class:: WKBReader
+
+Example::
+
+    >>> from django.contrib.gis.geos import WKBReader
+    >>> wkb_r = WKBReader()
+    >>> wkb_r.read('0101000000000000000000F03F000000000000F03F')
+    <Point object at 0x103a88910>
+
+.. class:: WKTReader
+
+Example::
+
+    >>> from django.contrib.gis.geos import WKTReader
+    >>> wkt_r = WKTReader()
+    >>> wkt_r.read('POINT(1 1)')
+    <Point object at 0x103a88b50>
+
+Writer Objects
+--------------
+
+All writer objects have a ``write(geom)`` method that returns either the
+WKB or WKT of the given geometry.  In addition, :class:`WKBWriter` objects
+also have properties that may be used to change the byte order, and or
+include the SRID and 3D values (in other words, EWKB).
+
+.. class:: WKBWriter
+
+``WKBWriter`` provides the most control over its output.  By default it
+returns OGC-compliant WKB when it's ``write`` method is called.  However, 
+it has properties that allow for the creation of EWKB, a superset of the
+WKB standard that includes additional information.
+
+.. method:: WKBWriter.write(geom)
+
+Returns the WKB of the given geometry as a Python ``buffer`` object.
+Example::
+
+    >>> from django.contrib.gis.geos import Point, WKBWriter
+    >>> pnt = Point(1, 1)
+    >>> wkb_w = WKBWriter()
+    >>> wkb_w.write(pnt)
+    <read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>
+
+.. method:: WKBWriter.write_hex(geom)
+
+Returns WKB of the geometry in hexadecimal.  Example::
+
+    >>> from django.contrib.gis.geos import Point, WKBWriter
+    >>> pnt = Point(1, 1)
+    >>> wkb_w = WKBWriter()
+    >>> wkb_w.write_hex(pnt)
+    '0101000000000000000000F03F000000000000F03F'
+
+.. attribute:: WKBWriter.byteorder
+
+This property may be be set to change the byte-order of the geometry
+representation.
+
+=============== =================================================
+Byteorder Value Description
+=============== =================================================
+0               Big Endian (e.g., compatible with RISC systems)
+1               Little Endian (e.g., compatible with x86 systems)
+=============== =================================================
+
+Example::
+
+    >>> from django.contrib.gis.geos import Point, WKBWriter
+    >>> wkb_w = WKBWriter()
+    >>> pnt = Point(1, 1)
+    >>> wkb_w.write_hex(pnt)
+    '0101000000000000000000F03F000000000000F03F'
+    >>> wkb_w.byteorder = 0
+    '00000000013FF00000000000003FF0000000000000'
+
+.. attribute:: WKBWriter.outdim
+
+This property may be set to change the output dimension of the geometry
+representation.  In other words, if you have a 3D geometry then set to 3
+so that the Z value is included in the WKB.
+
+============ ===========================
+Outdim Value Description
+============ ===========================
+2            The default, output 2D WKB.
+3            Output 3D EWKB.
+============ ===========================
+
+Example::
+
+    >>> from django.contrib.gis.geos import Point, WKBWriter
+    >>> wkb_w = WKBWriter()
+    >>> wkb_w.outdim
+    2
+    >>> pnt = Point(1, 1, 1)
+    >>> wkb_w.write_hex(pnt) # By default, no Z value included:
+    '0101000000000000000000F03F000000000000F03F'
+    >>> wkb_w.outdim = 3 # Tell writer to include Z values
+    >>> wkb_w.write_hex(pnt)
+    '0101000080000000000000F03F000000000000F03F000000000000F03F'
+
+.. attribute:: WKBWriter.srid
+
+Set this property with a boolean to indicate whether the SRID of the
+geometry should be included with the WKB representation.  Example::
+
+    >>> from django.contrib.gis.geos import Point, WKBWriter
+    >>> wkb_w = WKBWriter()
+    >>> pnt = Point(1, 1, srid=4326)
+    >>> wkb_w.write_hex(pnt) # By default, no SRID included:
+    '0101000000000000000000F03F000000000000F03F'
+    >>> wkb_w.srid = True # Tell writer to include SRID
+    >>> wkb_w.write_hex(pnt)
+    '0101000020E6100000000000000000F03F000000000000F03F'
+
+.. class:: WKTWriter
+
+.. method:: WKTWriter.write(geom)
+
+Returns the WKT of the given geometry. Example::
+
+    >>> from django.contrib.gis.geos import Point, WKTWriter
+    >>> pnt = Point(1, 1)
+    >>> wkt_w = WKTWriter()
+    >>> wkt_w.write(pnt)
+    'POINT (1.0000000000000000 1.0000000000000000)'
+
+
+.. rubric:: Footnotes
+.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/docs/ch04.html#id2591381>`_, PostGIS documentation at Ch. 4.1.2.
+.. [#fncascadedunion] For more information, read Paul Ramsey's blog post about `(Much) Faster Unions in PostGIS 1.4 <http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html>`_ and Martin Davis' blog post on `Fast polygon merging in JTS using Cascaded Union <http://lin-ear-th-inking.blogspot.com/2007/11/fast-polygon-merging-in-jts-using.html>`_.
+
+Settings
+========
+
+.. setting:: GEOS_LIBRARY_PATH
+
+GEOS_LIBRARY_PATH
+-----------------
+
+A string specifying the location of the GEOS C library.  Typically,
+this setting is only used if the GEOS C library is in a non-standard
+location (e.g., ``/home/bob/lib/libgeos_c.so``).
+
+.. note::
+
+    The setting must be the *full* path to the **C** shared library; in 
+    other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
diff --git a/parts/django/docs/ref/contrib/gis/index.txt b/parts/django/docs/ref/contrib/gis/index.txt
new file mode 100644
index 0000000..c4959e0
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/index.txt
@@ -0,0 +1,33 @@
+.. _ref-contrib-gis:
+
+=========
+GeoDjango
+=========
+
+.. versionadded:: 1.0
+
+.. module:: django.contrib.gis
+   :synopsis: Geographic Information System (GIS) extensions for Django
+
+GeoDjango intends to be a world-class geographic Web framework. Its goal is to
+make it as easy as possible to build GIS Web applications and harness the power
+of spatially enabled data.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorial
+   install
+   model-api
+   db-api
+   geoquerysets
+   measure
+   geos
+   gdal
+   utils
+   commands
+   admin
+   feeds
+   sitemaps
+   testing
+   deployment
diff --git a/parts/django/docs/ref/contrib/gis/install.txt b/parts/django/docs/ref/contrib/gis/install.txt
new file mode 100644
index 0000000..fa8e34c
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/install.txt
@@ -0,0 +1,1190 @@
+.. _ref-gis-install:
+
+======================
+GeoDjango Installation
+======================
+
+Overview
+========
+In general, GeoDjango installation requires:
+
+1. :ref:`python24` and :ref:`django`
+2. :ref:`spatial_database`
+3. :ref:`geospatial_libs`
+
+Details for each of the requirements and installation instructions
+are provided in the sections below.   In addition, platform-specific
+instructions are available for:
+
+* :ref:`macosx`
+* :ref:`ubuntudebian`
+* :ref:`windows`
+
+.. admonition:: Use the Source
+
+    Because GeoDjango takes advantage of the latest in the open source geospatial
+    software technology, recent versions of the libraries are necessary.
+    If binary packages aren't available for your platform,
+    :ref:`installation from source <build_from_source>`
+    may be required. When compiling the libraries from source, please follow the
+    directions closely, especially if you're a beginner.
+
+Requirements
+============
+
+.. _python24:
+
+Python 2.4+
+-----------
+
+Python 2.4 is the minimum version supported by Django, however Python 2.5+ is
+recommended because the `ctypes`__ module comes included; otherwise, 2.4 users
+will need to `download and install ctypes`__.
+
+__ http://docs.python.org/lib/module-ctypes.html
+__ http://sourceforge.net/projects/ctypes/files/
+
+.. _django:
+
+Django
+------
+
+Because GeoDjango is included with Django, please refer to Django's
+:doc:`installation instructions </intro/install>` for details on how to install.
+
+.. _spatial_database:
+
+Spatial Database
+----------------
+PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are
+the spatial databases currently supported.
+
+.. note::
+
+    PostGIS is recommended, because it is the most mature and feature-rich
+    open source spatial database.
+
+The geospatial libraries required for a GeoDjango installation depends
+on the spatial database used.  The following lists the library requirements,
+supported versions, and any notes for each of the supported database backends:
+
+==================  ==============================  ==================  ==========================================================
+Database            Library Requirements            Supported Versions  Notes
+==================  ==============================  ==================  ==========================================================
+PostgreSQL          GEOS, PROJ.4, PostGIS           8.1+                Requires PostGIS.
+MySQL               GEOS                            5.x                 Not OGC-compliant; limited functionality.
+Oracle              GEOS                            10.2, 11            XE not supported; not tested with 9.
+SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.6.+               Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.
+==================  ==============================  ==================  ==========================================================
+
+.. _geospatial_libs:
+
+Geospatial Libraries
+--------------------
+GeoDjango uses and/or provides interfaces for the the following open source
+geospatial libraries:
+
+========================  ====================================  ================================  ==========================
+Program                   Description                           Required                          Supported Versions
+========================  ====================================  ================================  ==========================
+:ref:`GEOS <ref-geos>`    Geometry Engine Open Source           Yes                               3.2, 3.1, 3.0
+`PROJ.4`_                 Cartographic Projections library      Yes (PostgreSQL and SQLite only)  4.7, 4.6, 4.5, 4.4
+:ref:`GDAL <ref-gdal>`    Geospatial Data Abstraction Library   No (but, required for SQLite)     1.7, 1.6, 1.5, 1.4
+:ref:`GeoIP <ref-geoip>`  IP-based geolocation library          No                                1.4
+`PostGIS`__               Spatial extensions for PostgreSQL     Yes (PostgreSQL only)             1.5, 1.4, 1.3
+`SpatiaLite`__            Spatial extensions for SQLite         Yes (SQLite only)                 2.4, 2.3
+========================  ====================================  ================================  ==========================
+
+.. admonition::  Install GDAL
+
+    While :ref:`gdalbuild` is technically not required, it is *recommended*.
+    Some features of GeoDjango (including the :ref:`ref-layermapping` and the geographic
+    admin) depend on its functionality.
+
+.. note::
+
+    The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
+    independently of Django.  In other words, no database or settings file
+    required -- just import them as normal from :mod:`django.contrib.gis`.
+
+.. _PROJ.4: http://trac.osgeo.org/proj/
+__ http://postgis.refractions.net/
+__ http://www.gaia-gis.it/spatialite/index.html
+
+.. _build_from_source:
+
+Building from Source
+====================
+
+When installing from source on UNIX and GNU/Linux systems, please follow
+the installation instructions carefully, and install the libraries in the
+given order.  If using MySQL or Oracle as the spatial database, only GEOS
+is required.
+
+.. note::
+
+   On Linux platforms, it may be necessarry to run the ``ldconfig``
+   command after installing each library.  For example::
+
+       $ sudo make install
+       $ sudo ldconfig
+
+.. note::
+
+    OS X users are required to install `Apple Developer Tools`_ in order
+    to compile software from source.  This is typically included on your
+    OS X installation DVDs.
+
+.. _Apple Developer Tools: http://developer.apple.com/tools/xcode/
+
+.. _geosbuild:
+
+GEOS
+----
+
+GEOS is a C++ library for performing geometric operations, and is the default
+internal geometry representation used by GeoDjango (it's behind the "lazy"
+geometries).  Specifically, the C API library is called (e.g., ``libgeos_c.so``)
+directly from Python using ctypes.
+
+First, download GEOS 3.2 from the refractions Web site and untar the source
+archive::
+
+    $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2
+    $ tar xjf geos-3.2.2.tar.bz2
+
+Next, change into the directory where GEOS was unpacked, run the configure
+script, compile, and install::
+
+    $ cd geos-3.2.2
+    $ ./configure
+    $ make
+    $ sudo make install
+    $ cd ..
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+Can't find GEOS Library
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When GeoDjango can't find GEOS, this error is raised::
+
+    ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
+
+The most common solution is to properly configure your :ref:`libsettings` *or* set
+:ref:`geoslibrarypath` in your settings.
+
+If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to :ref:`binutils`.
+
+.. _geoslibrarypath:
+
+``GEOS_LIBRARY_PATH``
+~~~~~~~~~~~~~~~~~~~~~
+
+If your GEOS library is in a non-standard location, or you don't want to
+modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`  setting
+may be added to your Django settings file with the full path to the GEOS
+C library.  For example::
+
+    GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
+
+.. note::
+
+    The setting must be the *full* path to the **C** shared library; in
+    other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
+
+.. _proj4:
+
+PROJ.4
+------
+
+`PROJ.4`_ is a library for converting geospatial data to different coordinate
+reference systems.
+
+First, download the PROJ.4 source code and datum shifting files [#]_::
+
+    $ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz
+    $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip
+
+Next, untar the source code archive, and extract the datum shifting files in the
+``nad`` subdirectory.  This must be done *prior* to configuration::
+
+    $ tar xzf proj-4.7.0.tar.gz
+    $ cd proj-4.7.0/nad
+    $ unzip ../../proj-datumgrid-1.5.zip
+    $ cd ..
+
+Finally, configure, make and install PROJ.4::
+
+    $ ./configure
+    $ make
+    $ sudo make install
+    $ cd ..
+
+.. _postgis:
+
+PostGIS
+-------
+
+`PostGIS`__ adds geographic object support to PostgreSQL, turning it
+into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be
+installed prior to building PostGIS.
+
+.. note::
+
+    The `psycopg2`_ module is required for use as the database adaptor
+    when using GeoDjango with PostGIS.
+
+.. _psycopg2: http://initd.org/projects/psycopg2
+
+First download the source archive, and extract::
+
+    $ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz
+    $ tar xzf postgis-1.5.2.tar.gz
+    $ cd postgis-1.5.2
+
+Next, configure, make and install PostGIS::
+
+    $ ./configure
+
+Finally, make and install::
+
+    $ make
+    $ sudo make install
+    $ cd ..
+
+.. note::
+
+    GeoDjango does not automatically create a spatial database.  Please
+    consult the section on :ref:`spatialdb_template` for more information.
+
+__ http://postgis.refractions.net/
+
+.. _gdalbuild:
+
+GDAL
+----
+
+`GDAL`__ is an excellent open source geospatial library that has support for
+reading most vector and raster spatial data formats.  Currently, GeoDjango only
+supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
+:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
+
+First download the latest GDAL release version and untar the archive::
+
+    $ wget http://download.osgeo.org/gdal/gdal-1.7.2.tar.gz
+    $ tar xzf gdal-1.7.2.tar.gz
+    $ cd gdal-1.7.2
+
+Configure, make and install::
+
+    $ ./configure
+    $ make # Go get some coffee, this takes a while.
+    $ sudo make install
+    $ cd ..
+
+.. note::
+
+   Because GeoDjango has it's own Python interface, the preceding instructions
+   do not build GDAL's own Python bindings.  The bindings may be built by
+   adding the ``--with-python`` flag when running ``configure``.  See
+   `GDAL/OGR In Python`__ for more information on GDAL's bindings.
+
+If you have any problems, please see the troubleshooting section below for
+suggestions and solutions.
+
+__ http://trac.osgeo.org/gdal/
+__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython
+
+.. _gdaltrouble:
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
+Can't find GDAL Library
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
+will be false::
+
+    >>> from django.contrib.gis import gdal
+    >>> gdal.HAS_GDAL
+    False
+
+The solution is to properly configure your :ref:`libsettings` *or* set
+:ref:`gdallibrarypath` in your settings.
+
+.. _gdallibrarypath:
+
+``GDAL_LIBRARY_PATH``
+~~~~~~~~~~~~~~~~~~~~~
+
+If your GDAL library is in a non-standard location, or you don't want to
+modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
+setting may be added to your Django settings file with the full path to
+the GDAL library.  For example::
+
+    GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
+
+.. _gdaldata:
+
+Can't find GDAL data files (``GDAL_DATA``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installed from source, GDAL versions 1.5.1 and below have an autoconf bug
+that places data in the wrong location. [#]_   This can lead to error messages
+like this::
+
+    ERROR 4: Unable to open EPSG support file gcs.csv.
+    ...
+    OGRException: OGR failure.
+
+The solution is to set the ``GDAL_DATA`` environment variable to the location of the
+GDAL data files before invoking Python  (typically ``/usr/local/share``; use
+``gdal-config --datadir`` to find out). For example::
+
+    $ export GDAL_DATA=`gdal-config --datadir`
+    $ python manage.py shell
+
+If using Apache, you may need to add this environment variable to your configuration
+file::
+
+    SetEnv GDAL_DATA /usr/local/share
+
+.. _spatialite:
+
+SpatiaLite
+----------
+.. versionadded:: 1.1
+
+.. note::
+
+   Mac OS X users should follow the instructions in the :ref:`kyngchaos` section,
+   as it is much easier than building from source.
+
+`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured
+spatial database.  Because SpatiaLite has special requirements, it typically
+requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from
+source.  :ref:`geosbuild` and :ref:`proj4` should be installed prior to building
+SpatiaLite.
+
+After installation is complete, don't forget to read the post-installation
+docs on :ref:`create_spatialite_db`.
+
+__ http://www.gaia-gis.it/spatialite/index.html
+
+.. _sqlite:
+
+SQLite
+^^^^^^
+
+Typically, SQLite packages are not compiled to include the `R*Tree module`__ --
+thus it must be compiled from source.  First download the latest amalgamation
+source archive from the `SQLite download page`__, and extract::
+
+    $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz
+    $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz
+    $ cd sqlite-3.6.23.1
+
+Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable
+needs to be customized so that SQLite knows to build the R*Tree module::
+
+    $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure
+    $ make
+    $ sudo make install
+    $ cd ..
+
+.. note::
+
+    If using Ubuntu, installing a newer SQLite from source can be very difficult
+    because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which
+    many other packages depend on.  Unfortunately, the best solution at this time
+    is to overwrite the existing library by adding ``--prefix=/usr`` to the
+    ``configure`` command.
+
+__ http://www.sqlite.org/rtree.html
+__ http://www.sqlite.org/download.html
+
+.. _spatialitebuild :
+
+SpatiaLite Library (``libspatialite``) and Tools (``spatialite``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After SQLite has been built with the R*Tree module enabled, get the latest
+SpatiaLite library source and tools bundle from the `download page`__::
+
+    $ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
+    $ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
+    $ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
+    $ tar xzf spatialite-tools-2.3.1.tar.gz
+
+Prior to attempting to build, please read the important notes below to see if
+customization of the ``configure`` command is necessary.  If not, then run the
+``configure`` script, make, and install for the SpatiaLite library::
+
+    $ cd libspatialite-amalgamation-2.3.1
+    $ ./configure # May need to modified, see notes below.
+    $ make
+    $ sudo make install
+    $ cd ..
+
+Finally, do the same for the SpatiaLite tools::
+
+    $ cd spatialite-tools-2.3.1
+    $ ./configure # May need to modified, see notes below.
+    $ make
+    $ sudo make install
+    $ cd ..
+
+.. note::
+
+    If you've installed GEOS and PROJ.4 from binary packages, you will have to specify
+    their paths when running the ``configure`` scripts for *both* the library and the
+    tools (the configure scripts look, by default, in ``/usr/local``).  For example,
+    on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be::
+
+       $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib
+
+.. note::
+
+    For Mac OS X users building from source, the SpatiaLite library *and* tools
+    need to have their ``target`` configured::
+
+        $ ./configure --target=macosx
+
+__ http://www.gaia-gis.it/spatialite/sources.html
+
+.. _pysqlite2:
+
+pysqlite2
+^^^^^^^^^
+
+Because SpatiaLite must be loaded as an external extension, it requires the
+``enable_load_extension`` method, which is only available in versions 2.5+.
+Thus, download pysqlite2 2.6, and untar::
+
+    $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
+    $ tar xzf pysqlite-2.6.0.tar.gz
+    $ cd pysqlite-2.6.0
+
+Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file
+to look like the following::
+
+    [build_ext]
+    #define=
+    include_dirs=/usr/local/include
+    library_dirs=/usr/local/lib
+    libraries=sqlite3
+    #define=SQLITE_OMIT_LOAD_EXTENSION
+
+.. note::
+
+    The important thing here is to make sure you comment out the the
+    ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs``
+    and ``library_dirs`` settings are uncommented and set to the appropriate
+    path if the SQLite header files and libraries are not in ``/usr/include``
+    and ``/usr/lib``, respectively.
+
+After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
+to build and install::
+
+    $ sudo python setup.py install
+
+Post-Installation
+=================
+
+.. _spatialdb_template:
+
+Creating a Spatial Database Template for PostGIS
+------------------------------------------------
+
+Creating a spatial database with PostGIS is different than normal because
+additional SQL must be loaded to enable spatial functionality.  Because of
+the steps in this process, it's better to create a database template that
+can be reused later.
+
+First, you need to be able to execute the commands as a privileged database
+user.  For example, you can use the following to become the ``postgres`` user::
+
+    $ sudo su - postgres
+
+.. note::
+
+   The location *and* name of the PostGIS SQL files (e.g., from
+   ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS.
+   PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``;
+   whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and
+   version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``.
+
+   The example below assumes PostGIS 1.5, thus you may need to modify
+   ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific
+   version of PostGIS you are using.
+
+Once you're a database super user, then you may execute the following commands
+to create a PostGIS spatial database template.  If running Ubuntu :ref:`ibex`
+or Debian :ref:`lenny`, please refer to their specific documentation for
+modifications to these commands::
+
+    $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
+    # Creating the template spatial database.
+    $ createdb -E UTF8 template_postgis
+    $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+    # Allows non-superusers the ability to create from this template
+    $ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+    # Loading the PostGIS SQL routines
+    $ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
+    $ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+    # Enabling users to alter spatial tables.
+    $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
+    $ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
+    $ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
+
+These commands may be placed in a shell script for later use; for convenience
+the following scripts are available:
+
+===============  ==========================================
+PostGIS Version  Shell Script
+===============  ==========================================
+1.3              `create_template_postgis-1.3.sh`_
+1.4              `create_template_postgis-1.4.sh`_
+1.5              `create_template_postgis-1.5.sh`_
+===============  ==========================================
+
+Afterwards, you may create a spatial database by simply specifying
+``template_postgis`` as the template to use (via the ``-T`` option)::
+
+    $ createdb -T template_postgis <db name>
+
+.. note::
+
+    While the ``createdb`` command does not require database super-user privileges,
+    it must be executed by a database user that has permissions to create databases.
+    You can create such a user with the following command::
+
+        $ createuser --createdb <user>
+
+.. _create_template_postgis-1.3.sh: http://geodjango.org/docs/create_template_postgis-1.3.sh
+.. _create_template_postgis-1.4.sh: http://geodjango.org/docs/create_template_postgis-1.4.sh
+.. _create_template_postgis-1.5.sh: http://geodjango.org/docs/create_template_postgis-1.5.sh
+.. _create_template_postgis-debian.sh: http://geodjango.org/docs/create_template_postgis-debian.sh
+
+.. _create_spatialite_db:
+
+Creating a Spatial Database for SpatiaLite
+-------------------------------------------
+
+After the SpatiaLite library and tools have been installed, it is now possible
+to create spatial database for use with GeoDjango.  In order to do this, download
+the spatial database initialization SQL from the `SpatiaLite Resources`__ page::
+
+   $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz
+   $ gunzip init_spatialite-2.3.sql.gz
+
+Now, the ``spatialite`` command can be used to initialize a spatial database::
+
+   $ spatialite geodjango.db < init_spatialite-2.3.sql
+
+.. note::
+
+    The parameter ``geodjango.db`` is the *filename* of the SQLite database
+    you want to use.  Use the same in the :setting:`DATABASE_NAME`
+    inside your ``settings.py``.
+
+
+__ http://www.gaia-gis.it/spatialite/resources.html
+
+
+Add ``django.contrib.gis`` to ``INSTALLED_APPS``
+------------------------------------------------
+
+Like other Django contrib applications, you will *only* need to add
+:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings.
+This is the so that ``gis`` templates can be located -- if not done, then
+features such as the geographic admin or KML sitemaps will not function properly.
+
+.. _addgoogleprojection:
+
+Add Google Projection to ``spatial_ref_sys`` table
+--------------------------------------------------
+
+.. versionchanged:: 1.2
+
+.. note::
+
+    If running PostGIS 1.4 and above, the entry is already included in the
+    default ``spatial_ref_sys`` table.  You can skip this step.
+
+In order to conduct database transformations to the so-called "Google"
+projection (a spherical mercator projection used by Google Maps),
+an entry must be added to your spatial database's ``spatial_ref_sys`` table.
+Invoke the Django shell from your project and execute the
+``add_srs_entry`` function::
+
+    $ python manage shell
+    >>> from django.contrib.gis.utils import add_srs_entry
+    >>> add_srs_entry(900913)
+
+.. note::
+
+    In Django 1.1 the name of this function is ``add_postgis_srs``.
+
+This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
+table, making it possible for the spatial database to transform coordinates in
+this projection.  You only need to execute this command *once* per spatial database.
+
+Troubleshooting
+===============
+
+If you can't find the solution to your problem here then participate in the
+community!  You can:
+
+* Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the
+  Web via `Mibbit`__).  Please be patient and polite -- while you may not
+  get an immediate response, someone will attempt to answer your question
+  as soon as they see it.
+* Ask your question on the `GeoDjango`__ mailing list.
+* File a ticket on the `Django trac`__ if you think there's a bug.  Make
+  sure to provide a complete description of the problem, versions used,
+  and specify the component as "GIS".
+
+__ http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango
+__ http://groups.google.com/group/geodjango
+__ http://code.djangoproject.com/simpleticket
+
+.. _libsettings:
+
+Library Environment Settings
+----------------------------
+
+By far, the most common problem when installing GeoDjango is that the
+external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_
+Typically, the cause of this problem is that the operating system isn't aware
+of the directory where the libraries built from source were installed.
+
+In general, the library path may be set on a per-user basis by setting
+an environment variable, or by configuring the library path for the entire
+system.
+
+``LD_LIBRARY_PATH`` environment variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A user may set this environment variable to customize the library paths
+they want to use.  The typical library directory for software
+built from source is ``/usr/local/lib``.  Thus, ``/usr/local/lib`` needs
+to be included in the ``LD_LIBRARY_PATH`` variable.  For example, the user
+could place the following in their bash profile::
+
+    export LD_LIBRARY_PATH=/usr/local/lib
+
+Setting System Library Path
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
+additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
+As the root user, add the custom library path (like ``/usr/local/lib``) on a
+new line in ``ld.so.conf``.  This is *one* example of how to do so::
+
+    $ sudo echo /usr/local/lib >> /etc/ld.so.conf
+    $ sudo ldconfig
+
+For OpenSolaris users, the system library path may be modified using the
+``crle`` utility.  Run ``crle`` with no options to see the current configuration
+and use ``crle -l`` to set with the new library path.  Be *very* careful when
+modifying the system library path::
+
+    # crle -l $OLD_PATH:/usr/local/lib
+
+.. _binutils:
+
+Install ``binutils``
+^^^^^^^^^^^^^^^^^^^^
+
+GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
+module) to discover libraries.  The ``find_library`` routine uses a program
+called ``objdump`` (part of the ``binutils`` package) to verify a shared
+library on GNU/Linux systems.  Thus, if ``binutils`` is not installed on your
+Linux system then Python's ctypes may not be able to find your library even if
+your library path is set correctly and geospatial libraries were built perfectly.
+
+The ``binutils`` package may be installed on Debian and Ubuntu systems using the
+following command::
+
+    $ sudo apt-get install binutils
+
+Similarly, on Red Hat and CentOS systems::
+
+    $ sudo yum install binutils
+
+Platform Specific Instructions
+==============================
+
+.. _macosx:
+
+Mac OS X
+--------
+
+Because of the variety of packaging systems available for OS X, users have
+several different options for installing GeoDjango.  These options are:
+
+* :ref:`kyngchaos`
+* :ref:`fink`
+* :ref:`macports`
+* :ref:`build_from_source`
+
+.. note::
+
+    Currently, the easiest and recommended approach for installing GeoDjango
+    on OS X is to use the KyngChaos packages.
+
+This section also includes instructions for installing an upgraded version
+of :ref:`macosx_python` from packages provided by the Python Software
+Foundation, however, this is not required.
+
+.. _macosx_python:
+
+Python
+^^^^^^
+
+Although OS X comes with Python installed, users can use framework
+installers (`2.5`__ and `2.6`__ are available) provided by
+the Python Software Foundation.  An advantage to using the installer is
+that OS X's Python will remain "pristine" for internal operating system
+use.
+
+__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
+__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
+
+.. note::
+
+    You will need to modify the ``PATH`` environment variable in your
+    ``.profile`` file so that the new version of Python is used when
+    ``python`` is entered at the command-line::
+
+        export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH
+
+.. _kyngchaos:
+
+KyngChaos Packages
+^^^^^^^^^^^^^^^^^^
+
+William Kyngesburye provides a number of `geospatial library binary packages`__
+that make it simple to get GeoDjango installed on OS X without compiling
+them from source.  However, the `Apple Developer Tools`_ are still necessary
+for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS)
+and :ref:`pysqlite2_kyngchaos` (for SpatiaLite).
+
+.. note::
+
+    SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section
+    after installing the packages for additional instructions.
+
+Download the framework packages for:
+
+* UnixImageIO
+* PROJ
+* GEOS
+* SQLite3 (includes the SpatiaLite library)
+* GDAL
+
+Install the packages in the order they are listed above, as the GDAL and SQLite
+packages require the packages listed before them.  Afterwards, you can also
+install the KyngChaos binary packages for `PostgreSQL and PostGIS`__.
+
+After installing the binary packages, you'll want to add the following to
+your ``.profile`` to be able to run the package programs from the command-line::
+
+    export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH
+    export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH
+    export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH
+    export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH
+    export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH
+    export PATH=/usr/local/pgsql/bin:$PATH
+
+__ http://www.kyngchaos.com/software/frameworks
+__ http://www.kyngchaos.com/software/postgres
+
+.. note::
+
+    Use of these binaries requires Django 1.0.3 and above.  If you are
+    using a previous version of Django (like 1.0.2), then you will have
+    to add the the following in your settings::
+
+        GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS'
+        GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL'
+
+.. _psycopg2_kyngchaos:
+
+psycopg2
+~~~~~~~~
+
+After you've installed the KyngChaos binaries and modified your ``PATH``, as
+described above, ``psycopg2`` may be installed using the following command::
+
+    $ sudo python easy_install psycopg2
+
+.. note::
+
+   To use ``easy_install`` you'll need to install Python's `setuptools`_.
+
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+
+.. _pysqlite2_kyngchaos:
+
+pysqlite2
+~~~~~~~~~
+
+Follow the :ref:`pysqlite2` source install instructions, however,
+when editing the ``setup.cfg`` use the following instead::
+
+    [build_ext]
+    #define=
+    include_dirs=/Library/Frameworks/SQLite3.framework/unix/include
+    library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib
+    libraries=sqlite3
+    #define=SQLITE_OMIT_LOAD_EXTENSION
+
+.. _spatialite_kyngchaos:
+
+SpatiaLite
+~~~~~~~~~~
+
+When :ref:`create_spatialite_db`, the ``spatialite`` program is required.
+However, instead of attempting to compile the SpatiaLite tools from source,
+download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a
+location available in your ``PATH``.  For example::
+
+    $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz
+    $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz
+    $ cd spatialite-tools-osx-x86-2.3.1/bin
+    $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs
+
+Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library,
+add the following to your ``settings.py``::
+
+    SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
+
+__ http://www.gaia-gis.it/spatialite/binaries.html
+
+.. _fink:
+
+Fink
+^^^^
+
+`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users
+of the `Fink`__ package system.  The following packages are available, depending
+on which version of Python you want to use:
+
+* ``django-gis-py26``
+* ``django-gis-py25``
+* ``django-gis-py24``
+
+__ http://schwehr.org/blog/
+__ http://www.finkproject.org/
+
+.. _macports:
+
+MacPorts
+^^^^^^^^
+
+`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
+computers running OS X.  Because MacPorts still builds the software from source,
+the `Apple Developer Tools`_ are required.
+
+Summary::
+
+    $ sudo port install postgresql83-server
+    $ sudo port install geos
+    $ sudo port install proj
+    $ sudo port install postgis
+    $ sudo port install gdal
+    $ sudo port install libgeoip
+
+.. note::
+
+    You will also have to modify the ``PATH`` in your ``.profile`` so
+    that the MacPorts programs are accessible from the command-line::
+
+        export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin
+
+    In addition, add the ``FALLBACK_DYLD_LIBRARY_PATH`` setting so that
+    the libraries can be found by Python::
+
+        export FALLBACK_DYLD_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83
+
+__ http://www.macports.org/
+
+.. _ubuntudebian:
+
+Ubuntu & Debian GNU/Linux
+-------------------------
+
+.. _ubuntu:
+
+Ubuntu
+^^^^^^
+
+.. _heron:
+
+8.04 and lower
+~~~~~~~~~~~~~~
+
+The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
+which is incompatible with GeoDjango.  Thus, do *not* use the binary packages
+for GEOS or PostGIS and build some prerequisites from source, per the instructions
+in this document; however, it is okay to use the PostgreSQL binary packages.
+
+For more details, please see the Debian instructions for :ref:`etch` below.
+
+.. _ibex:
+
+8.10
+~~~~
+
+Use the synaptic package manager to install the following packages::
+
+    $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools
+
+Afterwards, you may install Django with Python's ``easy_install`` script (the
+Ubuntu package ``python-django`` uses an older version missing several
+important bug fixes for GeoDjango)::
+
+    $ sudo easy_install Django
+
+That's it!  For the curious, the required binary prerequisites packages are:
+
+* ``binutils``: for ctypes to find libraries
+* ``postgresql-8.3``
+* ``postgresql-server-dev-8.3``: for ``pg_config``
+* ``postgresql-8.3-postgis``: for PostGIS 1.3.3
+* ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0
+* ``libgdal1-1.5.0``: for GDAL 1.5.0 library
+* ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
+* ``python-psycopg2``
+* ``python-setuptools``: for ``easy_install``
+
+Optional packages to consider:
+
+* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support
+* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
+* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
+
+.. note::
+
+    The Ubuntu ``proj`` package does not come with the datum shifting files
+    installed, which will cause problems with the geographic admin because
+    the ``null`` datum grid is not available for transforming geometries to the
+    spherical mercator projection. A solution is to download the
+    datum-shifting files, create the grid file, and install it yourself::
+
+        $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz
+        $ mkdir nad
+        $ cd nad
+        $ tar xzf ../proj-datumgrid-1.4.tar.gz
+        $ nad2bin null < null.lla
+        $ sudo cp null /usr/share/proj
+
+    Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you
+    do not plan on doing any database transformation of geometries to the
+    Google projection (900913).
+
+.. note::
+
+    The PostGIS SQL files are not placed the PostgreSQL share directory in the
+    Ubuntu packages.  Use the `create_template_postgis-debian.sh`_ script
+    instead when :ref:`spatialdb_template`.
+
+.. _debian:
+
+Debian
+------
+
+.. _etch:
+
+4.0 (Etch)
+^^^^^^^^^^
+The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
+some packages must be built from source to work properly with GeoDjango.
+
+Binary Packages
+~~~~~~~~~~~~~~~
+The following command will install acceptable binary packages, as well as
+the development tools necessary to build the rest of the requirements::
+
+    $ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools
+
+Required package information:
+
+* ``binutils``: for ctypes to find libraries
+* ``bzip2``: for decompressing the source packages
+* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries
+* ``flex``: required to build PostGIS
+* ``postgresql-8.1``
+* ``postgresql-server-dev-8.1``: for ``pg_config``
+* ``python-ctypes``: Python 2.4 needs to have ctypes installed separately
+* ``python-psycopg2``
+* ``python-setuptools``: for ``easy_install``
+
+Optional packages:
+
+* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
+
+Source Packages
+~~~~~~~~~~~~~~~
+You will still have to install :ref:`geosbuild`, :ref:`proj4`,
+:ref:`postgis`, and :ref:`gdalbuild` from source.  Please follow the
+directions carefully.
+
+.. _lenny:
+
+5.0 (Lenny)
+^^^^^^^^^^^
+This version is comparable to Ubuntu :ref:`ibex`, so the command
+is very similar::
+
+    $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools
+
+This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3``
+in the above command with the appropriate PostgreSQL version.
+
+.. note::
+
+   Please read the note in the Ubuntu :ref:`ibex` install documentation
+   about the ``proj`` package -- it also applies here because the package does
+   not include the datum shifting files.
+
+.. _post_install:
+
+Post-installation Notes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If the PostgreSQL database cluster was not initiated after installing, then it
+can be created (and started) with the following command::
+
+    $ sudo pg_createcluster --start 8.3 main
+
+Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage
+the starting and stopping of PostgreSQL.
+
+In addition, the SQL files for PostGIS are placed in a different location on
+Debian 5.0 . Thus when :ref:`spatialdb_template` either:
+
+* Create a symbolic link to these files::
+
+    $ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3
+
+  If not running PostgreSQL 8.3, then  replace ``8.3`` in the command above with the correct version.
+
+* Or use the `create_template_postgis-debian.sh`_ to create the spatial database.
+
+.. _windows:
+
+Windows XP
+----------
+
+Python
+^^^^^^
+
+First, download the `Python 2.6 installer`__ from the Python Web site.  Next,
+execute the installer and use defaults, e.g., keep 'Install for all users'
+checked and the installation path set as ``C:\Python26``.
+
+.. note::
+
+    You may already have a version of Python installed in ``C:\python`` as ESRI
+    products sometimes install a copy there.  *You should still install a
+    fresh version of Python 2.6.*
+
+__ http://python.org/ftp/python/2.6.2/python-2.6.2.msi
+
+PostgreSQL
+^^^^^^^^^^
+
+First, select a mirror and download the latest `PostgreSQL 8.3 installer`__ from
+the EnterpriseDB Web site.
+
+.. note::
+
+   PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4.
+
+After downloading, simply click on the installer, follow the
+on-screen directions, and keep the default options (e.g., keep the installation
+path as ``C:\Program Files\PostgreSQL\8.3``).
+
+.. note::
+
+    This PostgreSQL installation process will create both a new windows user to be the
+    'postgres service account' and a special 'postgres superuser' to own the database
+    cluster. You will be prompted to set a password for both users (make sure to write
+    them down!). To see basic details on the 'service user' account right click on
+    'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools ->
+    Computer Management -> System Tools -> Local Users and Groups.
+
+If installed successfully, the PostgreSQL server will run in the background each time
+the system as started as a Windows service.  When finished, the installer should launch
+the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions
+below for more details.  A 'PostgreSQL 8.3' start menu group should be created that
+contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window
+in the PostgreSQL directory.
+
+__ http://www.enterprisedb.com/products/pgdownload.do#windows
+
+PostGIS
+^^^^^^^
+
+From the Application Stack Builder (Programs -> PostgreSQL 8.3), select
+'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu.  Next,
+select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree
+in the list.  Select only the default options during install (do not uncheck
+the option to create a default PostGIS database).
+
+.. note::
+
+    You will be prompted to enter your 'postgres superuser' password in the
+    'Database Connection Information' dialog.
+
+psycopg2
+^^^^^^^^
+
+The ``psycopg2`` Python module provides the interface between Python and the
+PostgreSQL database.  Download the `Windows installer`__ (v2.0.10) and run
+using the default settings. [#]_
+
+__ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe
+
+GeoDjango Installer
+^^^^^^^^^^^^^^^^^^^
+
+Download the `GeoDjango Installer`__; this was created [#]_ to simplify the rest
+of the process for installing GeoDjango on Windows platforms.  The installer
+automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid
+files), and configures the necessary environment variables.
+
+Once the installer has completed, log out and log back in so that the
+modifications to the system environment variables take effect, and you
+should be good to go.
+
+.. note::
+
+    The installer modifies the system ``Path`` environment variable to
+    include ``C:\Program Files\PostgreSQL\8.3\bin`` and
+    ``C:\Program Files\GeoDjango\bin``.  This is required so that Python
+    may find the GEOS DLL provided by PostGIS and the GDAL DLL provided
+    by the installer. The installer also sets the ``GDAL_DATA`` and
+    ``PROJ_LIB`` environment variables.
+
+__ http://geodjango.org/windows/GeoDjango_Installer.exe
+
+.. rubric:: Footnotes
+.. [#] The datum shifting files are needed for converting data to and from certain projections.
+       For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_
+       requires the ``null`` grid file only included in the extra datum shifting files.
+       It is easier to install the shifting files now, then to have debug a problem caused by their absence later.
+.. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL.
+.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
+.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_
+       routine from ``ctypes.util`` to locate shared libraries.
+.. [#] The ``psycopg2`` Windows installers are packaged and maintained by
+       `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_.
+.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_
+       GeoDjango mercurial repository.
diff --git a/parts/django/docs/ref/contrib/gis/layermapping.txt b/parts/django/docs/ref/contrib/gis/layermapping.txt
new file mode 100644
index 0000000..0b09e17
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/layermapping.txt
@@ -0,0 +1,220 @@
+.. _ref-layermapping:
+
+====================================
+``LayerMapping`` data import utility
+====================================
+
+.. module:: django.contrib.gis.utils.layermapping
+   :synopsis: Spatial data import utility for GeoDjango models.
+
+.. currentmodule:: django.contrib.gis.utils
+
+The :class:`LayerMapping` class provides a way to map the contents of
+vector spatial data files (e.g. shapefiles) intoto GeoDjango models.
+
+This utility grew out of the author's personal needs to eliminate
+the code repetition that went into pulling geometries and fields out of
+a vector layer, converting to another coordinate system (e.g. WGS84), and
+then inserting into a GeoDjango model.
+
+.. note::
+
+    Use of :class:`LayerMapping` requires GDAL.
+
+.. warning ::
+
+    GIS data sources, like shapefiles, may be very large.  If you find
+    that :class:`LayerMapping` is using too much memory, set
+    :setting:`DEBUG` to ``False`` in your settings.  When :setting:`DEBUG`
+    is set to ``True``, Django :ref:`automatically logs <faq-see-raw-sql-queries>`
+    *every* SQL query -- thus, when SQL statements contain geometries, it is
+    easy to consume more memory than is typical.
+
+Example
+=======
+
+1. You need a GDAL-supported data source, like a shapefile (here we're using
+   a simple polygon shapefile, ``test_poly.shp``, with three features)::
+
+    >>> from django.contrib.gis.gdal import DataSource
+    >>> ds = DataSource('test_poly.shp')
+    >>> layer = ds[0]
+    >>> print layer.fields # Exploring the fields in the layer, we only want the 'str' field.
+    ['float', 'int', 'str']
+    >>> print len(layer) # getting the number of features in the layer (should be 3)
+    3
+    >>> print layer.geom_type # Should be 'Polygon'
+    Polygon
+    >>> print layer.srs # WGS84 in WKT
+    GEOGCS["GCS_WGS_1984",
+        DATUM["WGS_1984",
+            SPHEROID["WGS_1984",6378137,298.257223563]],
+        PRIMEM["Greenwich",0],
+        UNIT["Degree",0.017453292519943295]]
+
+2. Now we define our corresponding Django model (make sure to use ``syncdb``)::
+
+    from django.contrib.gis.db import models
+
+    class TestGeo(models.Model):
+        name = models.CharField(max_length=25) # corresponds to the 'str' field
+        poly = models.PolygonField(srid=4269) # we want our model in a different SRID
+        objects = models.GeoManager()
+        def __unicode__(self):
+            return 'Name: %s' % self.name
+
+3. Use :class:`LayerMapping` to extract all the features and place them in the
+   database::
+
+    >>> from django.contrib.gis.utils import LayerMapping
+    >>> from geoapp.models import TestGeo
+    >>> mapping = {'name' : 'str', # The 'name' model field maps to the 'str' layer field.
+                   'poly' : 'POLYGON', # For geometry fields use OGC name.
+                   } # The mapping is a dictionary
+    >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping)
+    >>> lm.save(verbose=True) # Save the layermap, imports the data.
+    Saved: Name: 1
+    Saved: Name: 2
+    Saved: Name: 3
+
+Here, :class:`LayerMapping` just transformed the three geometries from the
+shapefile in their original spatial reference system (WGS84) to the spatial
+reference system of the GeoDjango model (NAD83).  If no spatial reference
+system is defined for the layer, use the ``source_srs`` keyword with a
+:class:`~django.contrib.gis.gdal.SpatialReference` object to specify one.
+
+``LayerMapping`` API
+====================
+
+.. class:: LayerMapping(model, data_source, mapping[, layer=0, source_srs=None, encoding=None, transaction_mode='commit_on_success', transform=True, unique=True, using='default'])
+
+The following are the arguments and keywords that may be used during
+instantiation of ``LayerMapping`` objects.
+
+=================  =========================================================
+Argument           Description
+=================  =========================================================
+``model``          The geographic model, *not* an instance.
+
+``data_source``    The path to the OGR-supported data source file
+                   (e.g., a shapefile).  Also accepts
+                   :class:`django.contrib.gis.gdal.DataSource` instances.
+
+``mapping``        A dictionary: keys are strings corresponding to
+                   the model field, and values correspond to
+                   string field names for the OGR feature, or if the
+                   model field is a geographic then it should
+                   correspond to the OGR geometry type,
+                   e.g., ``'POINT'``, ``'LINESTRING'``, ``'POLYGON'``.
+=================  =========================================================
+
+=====================  =====================================================
+Keyword Arguments
+=====================  =====================================================
+``layer``              The index of the layer to use from the Data Source
+                       (defaults to 0)
+
+``source_srs``         Use this to specify the source SRS manually (for
+                       example, some shapefiles don't come with a '.prj'
+                       file).  An integer SRID, WKT or PROJ.4 strings, and
+                       :class:`django.contrib.gis.gdal.SpatialReference`
+                       objects are accepted.
+
+``encoding``           Specifies the character set encoding of the strings
+                       in the OGR data source.  For example, ``'latin-1'``,
+                       ``'utf-8'``, and ``'cp437'`` are all valid encoding
+                       parameters.
+
+``transaction_mode``   May be ``'commit_on_success'`` (default) or
+                       ``'autocommit'``.
+
+``transform``          Setting this to False will disable coordinate
+                       transformations.  In other words, geometries will
+                       be inserted into the database unmodified from their
+                       original state in the data source.
+
+``unique``             Setting this to the name, or a tuple of names,
+                       from the given  model will create models unique
+                       only to the given name(s). Geometries will from
+                       each feature will be added into the collection
+                       associated with the unique model.  Forces
+                       the transaction mode to be ``'autocommit'``.
+
+``using``              New in version 1.2.  Sets the database to use when
+                       importing spatial data.  Default is ``'default'``
+=====================  =====================================================
+
+``save()`` Keyword Arguments
+----------------------------
+
+.. method:: LayerMapping.save([verbose=False, fid_range=False, step=False, progress=False, silent=False, stream=sys.stdout, strict=False])
+
+The ``save()`` method also accepts keywords.  These keywords are
+used for controlling output logging, error handling, and for importing
+specific feature ranges.
+
+===========================  =================================================
+Save Keyword Arguments       Description
+===========================  =================================================
+``fid_range``                May be set with a slice or tuple of
+                             (begin, end) feature ID's to map from
+                             the data source.  In other words, this
+                             keyword enables the user to selectively
+                             import a subset range of features in the
+                             geographic data source.
+
+``progress``                 When this keyword is set, status information
+                             will be printed giving the number of features
+                             processed and successfully saved.  By default,
+                             progress information will be printed every 1000
+                             features processed, however, this default may
+                             be overridden by setting this keyword with an
+                             integer for the desired interval.
+
+``silent``                   By default, non-fatal error notifications are
+                             printed to ``sys.stdout``, but this keyword may
+                             be set to disable these notifications.
+
+``step``                     If set with an integer, transactions will
+                             occur at every step interval. For example, if
+                             ``step=1000``, a commit would occur after the
+                             1,000th feature, the 2,000th feature etc.
+
+
+``stream``                   Status information will be written to this file
+                             handle.  Defaults to using ``sys.stdout``, but
+                             any object with a ``write`` method is supported.
+
+``strict``                   Execution of the model mapping will cease upon
+                             the first error encountered.  The default value
+                             (``False``)
+                             behavior is to attempt to continue.
+
+``verbose``                  If set, information will be printed
+                             subsequent to each model save
+                             executed on the database.
+===========================  =================================================
+
+Troubleshooting
+===============
+
+Running out of memory
+---------------------
+
+As noted in the warning at the top of this section, Django stores all SQL
+queries when ``DEBUG=True``.  Set ``DEBUG=False`` in your settings, and this
+should stop excessive memory use when running ``LayerMapping`` scripts.
+
+MySQL: ``max_allowed_packet`` error
+-----------------------------------
+
+If you encounter the following error when using ``LayerMapping`` and MySQL::
+
+    OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes")
+
+Then the solution is to increase the value of the ``max_allowed_packet``
+setting in your MySQL configuration.  For example, the default value may
+be something low like one megabyte -- the setting may be modified in MySQL's
+configuration file (``my.cnf``) in the ``[mysqld]`` section::
+
+    max_allowed_packet = 10M
diff --git a/parts/django/docs/ref/contrib/gis/measure.txt b/parts/django/docs/ref/contrib/gis/measure.txt
new file mode 100644
index 0000000..6971788
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/measure.txt
@@ -0,0 +1,180 @@
+.. _ref-measure:
+
+===================
+Measurement Objects
+===================
+
+.. module:: django.contrib.gis.measure
+   :synopsis: GeoDjango's distance and area measurment objects.
+
+The :mod:`django.contrib.gis.measure` module contains objects that allow
+for convenient representation of distance and area units of measure. [#]_
+Specifically, it implements two objects, :class:`Distance` and
+:class:`Area` -- both of which may be accessed via the
+:class:`D` and :class:`A` convenience aliases, respectively.
+
+Example
+=======
+
+:class:`Distance` objects may be instantiated using a keyword argument indicating the
+context of the units.  In the example below, two different distance objects are
+instantiated in units of kilometers (``km``) and miles (``mi``)::
+
+    >>> from django.contrib.gis.measure import Distance, D
+    >>> d1 = Distance(km=5)
+    >>> print d1
+    5.0 km
+    >>> d2 = D(mi=5) # `D` is an alias for `Distance`
+    >>> print d2
+    5.0 mi
+
+Conversions are easy, just access the preferred unit attribute to get a
+converted distance quantity::
+
+    >>> print d1.mi # Converting 5 kilometers to miles
+    3.10685596119
+    >>> print d2.km # Converting 5 miles to kilometers
+    8.04672
+
+Moreover, arithmetic operations may be performed between the distance
+objects::
+
+    >>> print d1 + d2 # Adding 5 miles to 5 kilometers
+    13.04672 km
+    >>> print d2 - d1 # Subtracting 5 kilometers from 5 miles
+    1.89314403881 mi
+
+Two :class:`Distance` objects multiplied together will yield an :class:`Area`
+object, which uses squared units of measure::
+
+    >>> a = d1 * d2 # Returns an Area object.
+    >>> print a
+    40.2336 sq_km
+
+To determine what the attribute abbreviation of a unit is, the ``unit_attname``
+class method may be used::
+
+    >>> print Distance.unit_attname('US Survey Foot')
+    survey_ft
+    >>> print Distance.unit_attname('centimeter')
+    cm
+
+.. _supported_units:
+
+Supported units
+===============
+
+=================================  ========================================
+Unit Attribute                     Full name or alias(es)
+=================================  ========================================
+``km``                             Kilometre, Kilometer
+``mi``                             Mile
+``m``                              Meter, Metre
+``yd``                             Yard
+``ft``                             Foot, Foot (International)
+``survey_ft``                      U.S. Foot, US survey foot
+``inch``                           Inches
+``cm``                             Centimeter
+``mm``                             Millimetre, Millimeter
+``um``                             Micrometer, Micrometre
+``british_ft``                     British foot (Sears 1922)
+``british_yd``                     British yard (Sears 1922)
+``british_chain_sears``            British chain (Sears 1922)
+``indian_yd``                      Indian yard, Yard (Indian)
+``sears_yd``                       Yard (Sears)
+``clarke_ft``                      Clarke's Foot
+``chain``                          Chain
+``chain_benoit``                   Chain (Benoit)
+``chain_sears``                    Chain (Sears)
+``british_chain_benoit``           British chain (Benoit 1895 B)
+``british_chain_sears_truncated``  British chain (Sears 1922 truncated)
+``gold_coast_ft``                  Gold Coast foot
+``link``                           Link
+``link_benoit``                    Link (Benoit)
+``link_sears``                     Link (Sears)
+``clarke_link``                    Clarke's link
+``fathom``                         Fathom
+``rod``                            Rod
+``nm``                             Nautical Mile
+``nm_uk``                          Nautical Mile (UK)
+``german_m``                       German legal metre
+=================================  ========================================
+
+.. note::
+
+    :class:`Area` attributes are the same as :class:`Distance` attributes,
+    except they are prefixed with ``sq_`` (area units are square in nature).
+    For example, ``Area(sq_m=2)`` creates an :class:`Area` object
+    representing two square meters.
+
+Measurement API
+===============
+
+``Distance``
+------------
+
+.. class:: Distance(**kwargs)
+
+   To initialize a distance object, pass in a keyword corresponding to
+   the desired :ref:`unit attribute name <supported_units>` set with
+   desired value.  For example, the following creates a distance
+   object representing 5 miles::
+
+       >>> dist = Distance(mi=5)
+
+   .. method:: __getattr__(unit_att)
+
+   Returns the distance value in units corresponding to the given unit
+   attribute.  For example::
+
+       >>> print dist.km
+       8.04672
+
+   .. classmethod:: unit_attname(unit_name)
+
+   Returns the distance unit attribute name for the given full unit name.
+   For example::
+
+       >>> Distance.unit_attname('Mile')
+       'mi'
+
+.. class:: D
+
+   Alias for :class:`Distance` class.
+
+``Area``
+--------
+
+.. class:: Area(**kwargs)
+
+   To initialize a distance object, pass in a keyword corresponding to
+   the desired :ref:`unit attribute name <supported_units>` set with
+   desired value.  For example, the following creates a distance
+   object representing 5 square miles::
+
+       >>> a = Area(sq_mi=5)
+
+   .. method:: __getattr__(unit_att)
+
+   Returns the area value in units corresponding to the given unit
+   attribute.  For example::
+
+       >>> print a.sq_km
+       12.949940551680001
+
+   .. classmethod:: unit_attname(unit_name)
+
+   Returns the area unit attribute name for the given full unit name.
+   For example::
+
+        >>> Area.unit_attname('Kilometer')
+        'sq_km'
+
+.. class:: A
+
+   Alias for :class:`Area` class.
+
+.. rubric:: Footnotes
+.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects,
+       and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_
+       and Geoff Biggs' PhD work on dimensioned units for robotics.
diff --git a/parts/django/docs/ref/contrib/gis/model-api.txt b/parts/django/docs/ref/contrib/gis/model-api.txt
new file mode 100644
index 0000000..6b50cf3
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/model-api.txt
@@ -0,0 +1,265 @@
+.. _ref-gis-model-api:
+
+===================
+GeoDjango Model API
+===================
+
+.. module:: django.contrib.gis.db.models
+   :synopsis: GeoDjango model and field API.
+
+This document explores the details of the GeoDjango Model API.  Throughout this
+section, we'll be using the following geographic model of a `ZIP code`__ as our
+example::
+
+    from django.contrib.gis.db import models
+
+    class Zipcode(models.Model):
+        code = models.CharField(max_length=5)
+        poly = models.PolygonField()
+        objects = models.GeoManager()
+
+__ http://en.wikipedia.org/wiki/ZIP_code
+
+Geometry Field Types
+====================
+
+Each of the following geometry field types correspond with the
+OpenGIS Simple Features specification [#fnogc]_.
+
+``GeometryField``
+-----------------
+
+.. class:: GeometryField
+
+``PointField``
+--------------
+
+.. class:: PointField
+
+``LineStringField``
+-------------------
+
+.. class:: LineStringField
+
+``PolygonField``
+----------------
+
+.. class:: PolygonField
+
+``MultiPointField``
+-------------------
+
+.. class:: MultiPointField
+
+``MultiLineStringField``
+------------------------
+
+.. class:: MultiLineStringField
+
+``MultiPolygonField``
+---------------------
+
+.. class:: MultiPolygonField
+
+``GeometryCollectionField``
+---------------------------
+
+.. class:: GeometryCollectionField
+
+.. _geometry-field-options:
+
+Geometry Field Options
+======================
+
+In addition to the regular :ref:`common-model-field-options` available for
+Django model fields, geometry fields have the following additional options.
+All are optional.
+
+``srid``
+--------
+
+.. attribute:: GeometryField.srid
+
+Sets the SRID [#fnogcsrid]_ (Spatial Reference System Identity) of the geometry field to
+the given value. Defaults to 4326 (also known as `WGS84`__, units are in degrees
+of longitude and latitude).
+
+__ http://en.wikipedia.org/wiki/WGS84
+
+.. _selecting-an-srid:
+
+Selecting an SRID
+^^^^^^^^^^^^^^^^^
+
+Choosing an appropriate SRID for your model is an important decision that the
+developer should consider carefully.  The SRID is an integer specifier that
+corresponds to the projection system that will be used to interpret the data
+in the spatial database. [#fnsrid]_  Projection systems give the context to the
+coordinates that specify a location.  Although the details of `geodesy`__ are
+beyond the scope of this documentation, the general problem is that the earth
+is spherical and representations of the earth (e.g., paper maps, Web maps)
+are not.
+
+Most people are familiar with using latitude and longitude to reference a
+location on the earth's surface.  However, latitude and longitude are angles,
+not distances. [#fnharvard]_  In other words, while the shortest path between two points on
+a flat surface is a straight line, the shortest path between two points on a curved
+surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_  Thus,
+additional computation is required to obtain distances in planar units (e.g.,
+kilometers and miles).  Using a geographic coordinate system may introduce
+complications for the developer later on.  For example, PostGIS versions 1.4
+and below do not have the capability to perform distance calculations between
+non-point geometries using geographic coordinate systems, e.g., constructing a
+query to  find all points within 5 miles of a county boundary stored as WGS84.
+[#fndist]_
+
+Portions of the earth's surface may projected onto a two-dimensional, or
+Cartesian, plane.  Projected coordinate systems are especially convenient
+for region-specific applications, e.g., if you know that your database will
+only cover geometries in `North Kansas`__, then you may consider using projection
+system specific to that region.  Moreover, projected coordinate systems are
+defined in Cartesian units (such as meters or feet), easing distance
+calculations.
+
+.. note::
+
+    If you wish to peform arbitrary distance queries using non-point
+    geometries in WGS84, consider upgrading to PostGIS 1.5. For
+    better performance, enable the :attr:`GeometryField.geography`
+    keyword so that :ref:`geography database type <geography-type>`
+    is used instead.
+
+Additional Resources:
+
+* `spatialreference.org`__: A Django-powered database of spatial reference
+  systems.
+* `The State Plane Coordinate System`__: A Web site covering the various
+  projection systems used in the United States.  Much of the U.S. spatial
+  data encountered will be in one of these coordinate systems rather than
+  in a geographic coordinate system such as WGS84.
+
+__ http://en.wikipedia.org/wiki/Geodesy
+__ http://en.wikipedia.org/wiki/Great_circle
+__ http://www.spatialreference.org/ref/epsg/2796/
+__ http://spatialreference.org/
+__ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
+
+``spatial_index``
+-----------------
+
+.. attribute:: GeometryField.spatial_index
+
+Defaults to ``True``.  Creates a spatial index for the given geometry
+field.
+
+.. note::
+
+    This is different from the ``db_index`` field option because spatial
+    indexes are created in a different manner than regular database
+    indexes.  Specifically, spatial indexes are typically created using
+    a variant of the R-Tree, while regular database indexes typically
+    use B-Trees.
+
+``dim``
+-------
+
+.. versionadded:: 1.2
+
+.. attribute:: GeometryField.dim
+
+This option may be used for customizing the coordinate dimension of the
+geometry field.  By default, it is set to 2, for representing two-dimensional
+geometries.  For spatial backends that support it, it may be set to 3 for
+three-dimensonal support.
+
+.. note::
+
+    At this time 3D support requires that GEOS 3.1 be installed, and is
+    limited only to the PostGIS spatial backend.
+
+``geography``
+-------------
+
+.. versionadded:: 1.2
+
+.. attribute:: GeometryField.geography
+
+If set to ``True``, this option will create a database column of
+type geography, rather than geometry.  Please refer to the
+:ref:`geography type <geography-type>` section below for more
+details.
+
+.. note::
+
+    Geography support is limited only to PostGIS 1.5+, and will
+    force the SRID to be 4326.
+
+.. _geography-type:
+
+Geography Type
+^^^^^^^^^^^^^^
+
+In PostGIS 1.5, the geography type was introduced -- it provides
+provides native support for spatial features represented with geographic
+coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_
+Unlike the plane used by a geometry type, the geography type uses a spherical
+representation of its data.  Distance and measurement operations
+performed on a geography column automatically employ great circle arc
+calculations and return linear units.  In other words, when ``ST_Distance``
+is called on two geographies, a value in meters is returned (as opposed
+to degrees if called on a geometry column in WGS84).
+
+Because geography calculations involve more mathematics, only a subset of the
+PostGIS spatial lookups are available for the geography type. Practically,
+this means that in addition to the :ref:`distance lookups <distance-lookups>`
+only the following additional :ref:`spatial lookups <spatial-lookups>` are
+available for geography columns:
+
+* :lookup:`bboverlaps`
+* :lookup:`coveredby`
+* :lookup:`covers`
+* :lookup:`intersects`
+
+For more information, the PostGIS documentation contains a helpful section on
+determining `when to use geography data type over geometry data type
+<http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_GeographyVSGeometry>`_.
+
+``GeoManager``
+==============
+
+.. currentmodule:: django.contrib.gis.db.models
+.. class:: GeoManager
+
+In order to conduct geographic queries, each geographic model requires
+a ``GeoManager`` model manager.  This manager allows for the proper SQL
+construction for geographic queries; thus, without it, all geographic filters
+will fail.  It should also be noted that ``GeoManager`` is required even if the
+model does not have a geographic field itself, e.g., in the case of a
+``ForeignKey`` relation to a model with a geographic field.  For example,
+if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
+model::
+
+    from django.contrib.gis.db import models
+    from django.contrib.localflavor.us.models import USStateField
+
+    class Address(models.Model):
+        num = models.IntegerField()
+        street = models.CharField(max_length=100)
+        city = models.CharField(max_length=100)
+        state = USStateField()
+        zipcode = models.ForeignKey(Zipcode)
+        objects = models.GeoManager()
+
+The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
+for example::
+
+    qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
+
+.. rubric:: Footnotes
+.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
+.. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
+.. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier.  However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.
+.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_.  This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems.
+.. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3.
+.. [#fndist] This limitation does not apply to PostGIS 1.5.  It should be noted that even in previous versions of PostGIS, this isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system.
+.. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details.
diff --git a/parts/django/docs/ref/contrib/gis/ogrinspect.txt b/parts/django/docs/ref/contrib/gis/ogrinspect.txt
new file mode 100644
index 0000000..ed285e0
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/ogrinspect.txt
@@ -0,0 +1,21 @@
+.. _ref-ogrinspect:
+
+==============
+OGR Inspection
+==============
+
+.. module:: django.contrib.gis.utils.ogrinspect
+   :synopsis: Utilities for inspecting OGR data sources.
+
+.. currentmodule:: django.contrib.gis.utils
+
+``ogrinspect``
+==============
+
+.. function:: ogrinspect(data_source, model_name[, **kwargs])
+    :noindex:
+
+``mapping``
+===========
+
+.. function:: mapping(data_source, [geom_name='geom', layer_key=0, multi_geom=False])
diff --git a/parts/django/docs/ref/contrib/gis/sitemaps.txt b/parts/django/docs/ref/contrib/gis/sitemaps.txt
new file mode 100644
index 0000000..75bddd3
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/sitemaps.txt
@@ -0,0 +1,27 @@
+===================
+Geographic Sitemaps
+===================
+
+Google's sitemap protocol has been recently extended to support geospatial
+content. [#]_   This includes the addition of the ``<url>`` child element
+``<geo:geo>``, which tells Google that the content located at the URL is
+geographic in nature. [#]_ 
+
+Example
+=======
+
+Reference
+=========
+
+``KMLSitemap``
+--------------
+
+``KMZSitemap``
+--------------
+
+``GeoRSSSitemap``
+-----------------
+
+.. rubric:: Footnotes
+.. [#] Google, Inc., `What is a Geo Sitemap? <http://www.google.com/support/webmasters/bin/answer.py?answer=94554>`_.
+.. [#] Google, Inc., `Submit Your Geo Content to Google <http://code.google.com/apis/kml/documentation/kmlSearch.html>`_.
diff --git a/parts/django/docs/ref/contrib/gis/testing.txt b/parts/django/docs/ref/contrib/gis/testing.txt
new file mode 100644
index 0000000..889b43a
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/testing.txt
@@ -0,0 +1,268 @@
+======================
+Testing GeoDjango Apps
+======================
+
+.. versionchanged:: 1.2
+
+In Django 1.2, the addition of :ref:`spatial-backends`
+simplified the process of testing GeoDjango applications.  Specifically, testing
+GeoDjango applications is now the same as :doc:`/topics/testing`.
+
+Included in this documentation are some additional notes and settings
+for :ref:`testing-postgis` and :ref:`testing-spatialite` users.
+
+.. note::
+
+    Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`.
+    See the :ref:`testing-1.1` section for more details.
+
+.. _testing-postgis:
+
+PostGIS
+=======
+
+Settings
+--------
+
+.. note::
+
+    The settings below have sensible defaults, and shouldn't require manual setting.
+
+.. setting:: POSTGIS_TEMPLATE
+
+``POSTGIS_TEMPLATE``
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+.. versionchanged:: 1.2
+
+This setting may be used to customize the name of the PostGIS template
+database to use.  In Django versions 1.2 and above, it automatically
+defaults to ``'template_postgis'`` (the same name used in the
+:ref:`installation documentation <spatialdb_template>`).
+
+.. note::
+
+    Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE`
+    with a value, for example::
+
+        POSTGIS_TEMPLATE='template_postgis'
+
+.. setting:: POSTGIS_VERSION
+
+``POSTGIS_VERSION``
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+When GeoDjango's spatial backend initializes on PostGIS, it has to perform
+a SQL query to determine the version in order to figure out what
+features are available.  Advanced users wishing to prevent this additional
+query may set the version manually using a 3-tuple of integers specifying
+the major, minor, and subminor version numbers for PostGIS.  For example,
+to configure for PostGIS 1.5.2 you would use::
+
+    POSTGIS_VERSION = (1, 5, 2)
+
+Obtaining Sufficient Privileges
+-------------------------------
+
+Depending on your configuration, this section describes several methods to
+configure a database user with sufficient privileges to run tests for
+GeoDjango applications on PostgreSQL.  If your
+:ref:`spatial database template <spatialdb_template>`
+was created like in the instructions, then your testing database user
+only needs to have the ability to create databases.  In other configurations,
+you may be required to use a database superuser.
+
+Create Database User
+^^^^^^^^^^^^^^^^^^^^
+
+To make database user with the ability to create databases, use the
+following command::
+
+    $ createuser --createdb -R -S <user_name>
+
+The ``-R -S`` flags indicate that we do not want the user to have the ability
+to create additional users (roles) or to be a superuser, respectively.
+
+Alternatively, you may alter an existing user's role from the SQL shell
+(assuming this is done from an existing superuser account)::
+
+    postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
+
+Create Database Superuser
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This may be done at the time the user is created, for example::
+
+    $ createuser --superuser <user_name>
+
+Or you may alter the user's role from the SQL shell (assuming this
+is done from an existing superuser account)::
+
+    postgres# ALTER ROLE <user_name> SUPERUSER;
+
+
+Create Local PostgreSQL Database
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Initialize database: ``initdb -D /path/to/user/db``
+
+2. If there's already a Postgres instance on the machine, it will need
+   to use a different TCP port than 5432. Edit ``postgresql.conf`` (in
+   ``/path/to/user/db``) to change the database port (e.g. ``port = 5433``).
+
+3. Start this database ``pg_ctl -D /path/to/user/db start``
+
+Windows
+-------
+
+On Windows platforms the pgAdmin III utility may also be used as
+a simple way to add superuser privileges to your database user.
+
+By default, the PostGIS installer on Windows includes a template
+spatial database entitled ``template_postgis``.
+
+.. _testing-spatialite:
+
+SpatiaLite
+==========
+
+.. versionadded:: 1.1
+
+You will need to download the `initialization SQL`__ script for SpatiaLite::
+
+    $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
+    $ unzip init_spatialite-2.3.zip
+
+If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``,
+then all you have to do is::
+
+    $ python manage.py test
+
+Settings
+--------
+
+.. setting:: SPATIALITE_SQL
+
+``SPATIALITE_SQL``
+^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
+same directory where it was invoked (by default the same directory where
+``manage.py`` is located).  If you want to use a different location, then
+you may add the following to your settings::
+
+    SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql'
+
+__ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip
+
+.. _testing-1.1:
+
+Testing GeoDjango Applications in 1.1
+=====================================
+
+In Django 1.1, to accommodate the extra steps required to scaffalod a
+spatial database automatically, a test runner customized for GeoDjango
+must be used.  To use this runner, configure :setting:`TEST_RUNNER` as follows::
+
+    TEST_RUNNER='django.contrib.gis.tests.run_tests'
+
+.. note::
+
+    In order to create a spatial database, the :setting:`USER` setting
+    (or :setting:`TEST_USER`, if optionally defined on Oracle) requires
+    elevated privileges.  When using PostGIS or MySQL, the database user
+    must have at least the ability to create databases.  When testing on Oracle,
+    the user should be a superuser.
+
+.. _geodjango-tests:
+
+GeoDjango Tests
+===============
+
+.. versionchanged:: 1.2.4
+
+GeoDjango's test suite may be run in one of two ways, either by itself or
+with the rest of Django's :ref:`unit-tests`.
+
+.. note::
+
+    The :setting:`TEST_RUNNER` previously used to execute the GeoDjango
+    test suite,:func:`django.contrib.gis.tests.run_gis_tests`, was deprecated
+    in favor of the :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`
+    class.
+
+Run only GeoDjango tests
+------------------------
+
+To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER`
+setting must be changed to use the
+:class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`::
+
+    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
+
+Example
+^^^^^^^
+
+First, you'll need a bare-bones settings file, like below, that is
+customized with your spatial database name and user::
+
+    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.contrib.gis.db.backends.postgis',
+            'NAME': 'a_spatial_database',
+            'USER': 'db_user'
+        }
+    }
+
+Assuming the above is in a file called ``postgis.py`` that is in the
+the same directory as ``manage.py`` of your Django project, then
+you may run the tests with the following command::
+
+    $ python manage.py test --settings=postgis
+
+Run with ``runtests.py``
+------------------------
+
+To have the GeoDjango tests executed when
+:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
+all of the databases in the settings file must be using one of the
+:ref:`spatial database backends <spatial-backends>`.
+
+.. warning::
+
+    Do not change the :setting:`TEST_RUNNER` setting 
+    when running the GeoDjango tests with ``runtests.py``.
+
+Example
+^^^^^^^
+
+The following is an example bare-bones settings file with spatial backends
+that can be used to run the entire Django test suite, including those
+in :mod:`django.contrib.gis`::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.contrib.gis.db.backends.postgis',
+            'NAME': 'geodjango',
+            'USER': 'geodjango',
+        },
+       'other': {
+            'ENGINE': 'django.contrib.gis.db.backends.postgis',
+            'NAME': 'other',
+            'USER': 'geodjango',
+       }
+    }
+
+Assuming the settings above were in a ``postgis.py`` file in the same
+directory as ``runtests.py``, then all Django and GeoDjango tests would
+be performed when executing the command::
+
+    $ ./runtests.py --settings=postgis
diff --git a/parts/django/docs/ref/contrib/gis/tutorial.txt b/parts/django/docs/ref/contrib/gis/tutorial.txt
new file mode 100644
index 0000000..9deeb78
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/tutorial.txt
@@ -0,0 +1,758 @@
+==================
+GeoDjango Tutorial
+==================
+
+Introduction
+============
+
+GeoDjango is an add-on for Django that turns it into a world-class geographic
+Web framework.  GeoDjango strives to make at as simple as possible to create
+geographic Web applications, like location-based services.  Some features include:
+
+* Django model fields for `OGC`_ geometries.
+* Extensions to Django's ORM for the querying and manipulation of spatial data.
+* Loosely-coupled, high-level Python interfaces for GIS geometry operations and
+  data formats.
+* Editing of geometry fields inside the admin.
+
+This tutorial assumes a familiarity with Django; thus, if you're brand new to
+Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce
+yourself with basic Django concepts.
+
+.. note::
+
+    GeoDjango has special prerequisites overwhat is required by Django --
+    please consult the :ref:`installation documentation <ref-gis-install>`
+    for more details.
+
+This tutorial will guide you through the creation of a geographic Web
+application for viewing the `world borders`_. [#]_ Some of the code
+used in this tutorial is taken from and/or inspired by the `GeoDjango
+basic apps`_ project. [#]_
+
+.. note::
+
+    Proceed through the tutorial sections sequentially for step-by-step
+    instructions.
+
+.. _OGC: http://www.opengeospatial.org/
+.. _world borders: http://thematicmapping.org/downloads/world_borders.php
+.. _GeoDjango basic apps: http://code.google.com/p/geodjango-basic-apps/
+
+Setting Up
+==========
+
+Create a Spatial Database
+-------------------------
+
+.. note::
+
+    MySQL and Oracle users can skip this section because spatial types
+    are already built into the database.
+
+First, a spatial database needs to be created for our project.  If using
+PostgreSQL and PostGIS, then the following commands will
+create the database from a :ref:`spatial database template <spatialdb_template>`::
+
+    $ createdb -T template_postgis geodjango
+
+.. note::
+
+    This command must be issued by a database user that has permissions to
+    create a database.  Here is an example set of commands to create such
+    a user::
+
+        $ sudo su - postgres
+        $ createuser --createdb geo
+        $ exit
+
+    Replace ``geo`` to correspond to the system login user name will be
+    connecting to the database.  For example, ``johndoe`` if that is the
+    system user that will be running GeoDjango.
+
+Users of SQLite and SpatiaLite should consult the instructions on how
+to create a :ref:`SpatiaLite database <create_spatialite_db>`.
+
+Create GeoDjango Project
+------------------------
+
+Use the ``django-admin.py`` script like normal to create a ``geodjango`` project::
+
+    $ django-admin.py startproject geodjango
+
+With the project initialized, now create a ``world`` Django application within
+the ``geodjango`` project::
+
+    $ cd geodjango
+    $ python manage.py startapp world
+
+Configure ``settings.py``
+-------------------------
+
+The ``geodjango`` project settings are stored in the ``settings.py`` file.  Edit
+the database connection settings appropriately::
+
+    DATABASES = {
+        'default': {
+             'ENGINE': 'django.contrib.gis.db.backends.postgis',
+             'NAME': 'geodjango',
+             'USER': 'geo',
+         }
+    }
+
+.. note::
+
+    These database settings are for Django 1.2 and above.
+
+In addition, modify the :setting:`INSTALLED_APPS` setting to include
+:mod:`django.contrib.admin`, :mod:`django.contrib.gis`,
+and ``world`` (our newly created application)::
+
+    INSTALLED_APPS = (
+        'django.contrib.auth',
+        'django.contrib.contenttypes',
+        'django.contrib.sessions',
+        'django.contrib.sites',
+        'django.contrib.admin',
+        'django.contrib.gis',
+        'world'
+    )
+
+Geographic Data
+===============
+
+.. _worldborders:
+
+World Borders
+-------------
+
+The world borders data is available in this `zip file`__.  Create a data directory
+in the ``world`` application, download the world borders data, and unzip.
+On GNU/Linux platforms the following commands should do it::
+
+    $ mkdir world/data
+    $ cd world/data
+    $ wget http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip
+    $ unzip TM_WORLD_BORDERS-0.3.zip
+    $ cd ../..
+
+The world borders ZIP file contains a set of data files collectively known as
+an `ESRI Shapefile`__, one of the most popular geospatial data formats.  When
+unzipped the world borders data set includes files with the following extensions:
+
+* ``.shp``: Holds the vector data for the world borders geometries.
+* ``.shx``: Spatial index file for geometries stored in the ``.shp``.
+* ``.dbf``: Database file for holding non-geometric attribute data
+  (e.g., integer and character fields).
+* ``.prj``: Contains the spatial reference information for the geographic
+  data stored in the shapefile.
+
+__ http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip
+__ http://en.wikipedia.org/wiki/Shapefile
+
+Use ``ogrinfo`` to examine spatial data
+---------------------------------------
+
+The GDAL ``ogrinfo`` utility is excellent for examining metadata about
+shapefiles (or other vector data sources)::
+
+    $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
+    INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
+          using driver `ESRI Shapefile' successful.
+    1: TM_WORLD_BORDERS-0.3 (Polygon)
+
+Here ``ogrinfo`` is telling us that the shapefile has one layer, and that
+layer contains polygon data.  To find out more we'll specify the layer name
+and use the ``-so`` option to get only important summary information::
+
+    $ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3
+    INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
+          using driver `ESRI Shapefile' successful.
+
+    Layer name: TM_WORLD_BORDERS-0.3
+    Geometry: Polygon
+    Feature Count: 246
+    Extent: (-180.000000, -90.000000) - (180.000000, 83.623596)
+    Layer SRS WKT:
+    GEOGCS["GCS_WGS_1984",
+        DATUM["WGS_1984",
+            SPHEROID["WGS_1984",6378137.0,298.257223563]],
+        PRIMEM["Greenwich",0.0],
+        UNIT["Degree",0.0174532925199433]]
+    FIPS: String (2.0)
+    ISO2: String (2.0)
+    ISO3: String (3.0)
+    UN: Integer (3.0)
+    NAME: String (50.0)
+    AREA: Integer (7.0)
+    POP2005: Integer (10.0)
+    REGION: Integer (3.0)
+    SUBREGION: Integer (3.0)
+    LON: Real (8.3)
+    LAT: Real (7.3)
+
+This detailed summary information tells us the number of features in the layer
+(246), the geographical extent, the spatial reference system ("SRS WKT"),
+as well as detailed information for each attribute field.  For example,
+``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field
+with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point
+field that holds a maximum of 8 digits up to three decimal places.  Although
+this information may be found right on the `world borders`_ Web site, this shows
+you how to determine this information yourself when such metadata is not
+provided.
+
+Geographic Models
+=================
+
+Defining a Geographic Model
+---------------------------
+
+Now that we've examined our world borders data set using ``ogrinfo``, we can
+create a GeoDjango model to represent this data::
+
+    from django.contrib.gis.db import models
+
+    class WorldBorders(models.Model):
+        # Regular Django fields corresponding to the attributes in the
+	# world borders shapefile.
+        name = models.CharField(max_length=50)
+        area = models.IntegerField()
+        pop2005 = models.IntegerField('Population 2005')
+        fips = models.CharField('FIPS Code', max_length=2)
+        iso2 = models.CharField('2 Digit ISO', max_length=2)
+        iso3 = models.CharField('3 Digit ISO', max_length=3)
+        un = models.IntegerField('United Nations Code')
+        region = models.IntegerField('Region Code')
+        subregion = models.IntegerField('Sub-Region Code')
+    	lon = models.FloatField()
+    	lat = models.FloatField()
+
+	# GeoDjango-specific: a geometry field (MultiPolygonField), and
+        # overriding the default manager with a GeoManager instance.
+	mpoly = models.MultiPolygonField()
+	objects = models.GeoManager()
+
+        # So the model is pluralized correctly in the admin.
+        class Meta:
+            verbose_name_plural = "World Borders"
+
+        # Returns the string representation of the model.
+        def __unicode__(self):
+            return self.name
+
+Two important things to note:
+
+1. The ``models`` module is imported from :mod:`django.contrib.gis.db`.
+2. The model overrides its default manager with
+   :class:`~django.contrib.gis.db.models.GeoManager`; this is *required*
+   to perform spatial queries.
+
+When declaring a geometry field on your model the default spatial reference system
+is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in
+longitude/latitude pairs in units of degrees.  If you want the coordinate system to be
+different, then SRID of the geometry field may be customized by setting the ``srid``
+with an integer corresponding to the coordinate system of your choice.
+
+__ http://en.wikipedia.org/wiki/SRID
+
+Run ``syncdb``
+--------------
+
+After you've defined your model, it needs to be synced with the spatial database.
+First, let's look at the SQL that will generate the table for the ``WorldBorders``
+model::
+
+    $ python manage.py sqlall world
+
+This management command should produce the following output::
+
+    BEGIN;
+    CREATE TABLE "world_worldborders" (
+        "id" serial NOT NULL PRIMARY KEY,
+        "name" varchar(50) NOT NULL,
+        "area" integer NOT NULL,
+        "pop2005" integer NOT NULL,
+        "fips" varchar(2) NOT NULL,
+        "iso2" varchar(2) NOT NULL,
+        "iso3" varchar(3) NOT NULL,
+        "un" integer NOT NULL,
+        "region" integer NOT NULL,
+        "subregion" integer NOT NULL,
+        "lon" double precision NOT NULL,
+        "lat" double precision NOT NULL
+    )
+    ;
+    SELECT AddGeometryColumn('world_worldborders', 'mpoly', 4326, 'MULTIPOLYGON', 2);
+    ALTER TABLE "world_worldborders" ALTER "mpoly" SET NOT NULL;
+    CREATE INDEX "world_worldborders_mpoly_id" ON "world_worldborders" USING GIST ( "mpoly" GIST_GEOMETRY_OPS );
+    COMMIT;
+
+If satisfied, you may then create this table in the database by running the
+``syncdb`` management command::
+
+    $ python manage.py syncdb
+    Creating table world_worldborders
+    Installing custom SQL for world.WorldBorders model
+
+The ``syncdb`` command may also prompt you to create an admin user; go ahead and
+do so (not required now, may be done at any point in the future using the
+``createsuperuser`` management command).
+
+Importing Spatial Data
+======================
+
+This section will show you how to take the data from the world borders
+shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`.
+There are many different different ways to import data in to a
+spatial database -- besides the tools included within GeoDjango, you
+may also use the following to populate your spatial database:
+
+* `ogr2ogr`_: Command-line utility, included with GDAL, that
+  supports loading a multitude of vector data formats into
+  the PostGIS, MySQL, and Oracle spatial databases.
+* `shp2pgsql`_: This utility is included with PostGIS and only supports
+  ESRI shapefiles.
+
+.. _ogr2ogr: http://www.gdal.org/ogr2ogr.html
+.. _shp2pgsql: http://postgis.refractions.net/documentation/manual-1.5/ch04.html#shp2pgsql_usage
+
+.. _gdalinterface:
+
+GDAL Interface
+--------------
+
+Earlier we used the the ``ogrinfo`` to explore the contents of the world borders
+shapefile.  Included within GeoDjango is an interface to GDAL's powerful OGR
+library -- in other words, you'll be able explore all the vector data sources
+that OGR supports via a Pythonic API.
+
+First, invoke the Django shell::
+
+    $ python manage.py shell
+
+If the :ref:`worldborders` data was downloaded like earlier in the
+tutorial, then we can determine the path using Python's built-in
+``os`` module::
+
+    >>> import os
+    >>> from geodjango import world
+    >>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__),
+    ...                             'data/TM_WORLD_BORDERS-0.3.shp'))
+
+Now, the world borders shapefile may be opened using GeoDjango's
+:class:`~django.contrib.gis.gdal.DataSource` interface::
+
+    >>> from django.contrib.gis.gdal import *
+    >>> ds = DataSource(world_shp)
+    >>> print ds
+    / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile)
+
+Data source objects can have different layers of geospatial features; however,
+shapefiles are only allowed to have one layer::
+
+    >>> print len(ds)
+    1
+    >>> lyr = ds[0]
+    >>> print lyr
+    TM_WORLD_BORDERS-0.3
+
+You can see what the geometry type of the layer is and how many features it
+contains::
+
+    >>> print lyr.geom_type
+    Polygon
+    >>> print len(lyr)
+    246
+
+.. note::
+
+    Unfortunately the shapefile data format does not allow for greater
+    specificity with regards to geometry types.  This shapefile, like
+    many others, actually includes ``MultiPolygon`` geometries in its
+    features.  You need to watch out for this when creating your models
+    as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon``
+    type geometry -- thus a ``MultiPolygonField`` is used in our model's
+    definition instead.
+
+The :class:`~django.contrib.gis.gdal.Layer` may also have a spatial reference
+system associated with it -- if it does, the ``srs`` attribute will return a
+:class:`~django.contrib.gis.gdal.SpatialReference` object::
+
+    >>> srs = lyr.srs
+    >>> print srs
+    GEOGCS["GCS_WGS_1984",
+        DATUM["WGS_1984",
+            SPHEROID["WGS_1984",6378137.0,298.257223563]],
+        PRIMEM["Greenwich",0.0],
+        UNIT["Degree",0.0174532925199433]]
+    >>> srs.proj4 # PROJ.4 representation
+    '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
+
+Here we've noticed that the shapefile is in the popular WGS84 spatial reference
+system -- in other words, the data uses units of degrees longitude and latitude.
+
+In addition, shapefiles also support attribute fields that may contain
+additional data.  Here are the fields on the World Borders layer:
+
+    >>> print lyr.fields
+    ['FIPS', 'ISO2', 'ISO3', 'UN', 'NAME', 'AREA', 'POP2005', 'REGION', 'SUBREGION', 'LON', 'LAT']
+
+Here we are examining the OGR types (e.g., whether a field is an integer or
+a string) associated with each of the fields:
+
+    >>> [fld.__name__ for fld in lyr.field_types]
+    ['OFTString', 'OFTString', 'OFTString', 'OFTInteger', 'OFTString', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTReal', 'OFTReal']
+
+You can iterate over each feature in the layer and extract information from both
+the feature's geometry (accessed via the ``geom`` attribute) as well as the
+feature's attribute fields (whose **values** are accessed via ``get()``
+method)::
+
+    >>> for feat in lyr:
+    ...    print feat.get('NAME'), feat.geom.num_points
+    ...
+    Guernsey 18
+    Jersey 26
+    South Georgia South Sandwich Islands 338
+    Taiwan 363
+
+:class:`~django.contrib.gis.gdal.Layer` objects may be sliced::
+
+    >>> lyr[0:2]
+    [<django.contrib.gis.gdal.feature.Feature object at 0x2f47690>, <django.contrib.gis.gdal.feature.Feature object at 0x2f47650>]
+
+And individual features may be retrieved by their feature ID::
+
+    >>> feat = lyr[234]
+    >>> print feat.get('NAME')
+    San Marino
+
+Here the boundary geometry for San Marino is extracted and looking
+exported to WKT and GeoJSON::
+
+    >>> geom = feat.geom
+    >>> print geom.wkt
+    POLYGON ((12.415798 43.957954,12.450554 ...
+    >>> print geom.json
+    { "type": "Polygon", "coordinates": [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ...
+
+
+``LayerMapping``
+----------------
+
+We're going to dive right in -- create a file called ``load.py`` inside the
+``world`` application, and insert the following::
+
+    import os
+    from django.contrib.gis.utils import LayerMapping
+    from models import WorldBorders
+
+    world_mapping = {
+        'fips' : 'FIPS',
+        'iso2' : 'ISO2',
+        'iso3' : 'ISO3',
+        'un' : 'UN',
+        'name' : 'NAME',
+        'area' : 'AREA',
+        'pop2005' : 'POP2005',
+        'region' : 'REGION',
+        'subregion' : 'SUBREGION',
+        'lon' : 'LON',
+        'lat' : 'LAT',
+        'mpoly' : 'MULTIPOLYGON',
+    }
+
+    world_shp = os.path.abspath(os.path.join(os.path.dirname(__file__), 'data/TM_WORLD_BORDERS-0.3.shp'))
+
+    def run(verbose=True):
+        lm = LayerMapping(WorldBorders, world_shp, world_mapping,
+                          transform=False, encoding='iso-8859-1')
+
+        lm.save(strict=True, verbose=verbose)
+
+A few notes about what's going on:
+
+* Each key in the ``world_mapping`` dictionary corresponds to a field in the
+  ``WorldBorders`` model, and the value is the name of the shapefile field
+  that data will be loaded from.
+* The key ``mpoly`` for the geometry field is ``MULTIPOLYGON``, the
+  geometry type we wish to import as.  Even if simple polygons are encountered
+  in the shapefile they will automatically be converted into collections prior
+  to insertion into the database.
+* The path to the shapefile is not absolute -- in other words, if you move the
+  ``world`` application (with ``data`` subdirectory) to a different location,
+  then the script will still work.
+* The ``transform`` keyword is set to ``False`` because the data in the
+  shapefile does not need to be converted -- it's already in WGS84 (SRID=4326).
+* The ``encoding`` keyword is set to the character encoding of string values in
+  the shapefile. This ensures that string values are read and saved correctly
+  from their original encoding system.
+
+Afterwards, invoke the Django shell from the ``geodjango`` project directory::
+
+   $ python manage.py shell
+
+Next, import the ``load`` module, call the ``run`` routine, and watch ``LayerMapping``
+do the work::
+
+   >>> from world import load
+   >>> load.run()
+
+
+.. _ogrinspect-intro:
+
+Try ``ogrinspect``
+------------------
+Now that you've seen how to define geographic models and import data with the
+:ref:`ref-layermapping`, it's possible to further automate this process with
+use of the :djadmin:`ogrinspect` management command.  The :djadmin:`ogrinspect`
+command  introspects a GDAL-supported vector data source (e.g., a shapefile) and
+generates a model definition and ``LayerMapping`` dictionary automatically.
+
+The general usage of the command goes as follows::
+
+    $ python manage.py ogrinspect [options] <data_source> <model_name> [options]
+
+Where ``data_source`` is the path to the GDAL-supported data source and
+``model_name`` is the name to use for the model.  Command-line options may
+be used to further define how the model is generated.
+
+For example, the following command nearly reproduces the ``WorldBorders`` model
+and mapping dictionary created above, automatically::
+
+    $ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorders --srid=4326 --mapping --multi
+
+A few notes about the command-line options given above:
+
+* The ``--srid=4326`` option sets the SRID for the geographic field.
+* The ``--mapping`` option tells ``ogrinspect`` to also generate a
+  mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`.
+* The ``--multi`` option is specified so that the geographic field is a
+  :class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a
+  :class:`~django.contrib.gis.db.models.PolygonField`.
+
+The command produces the following output, which may be copied
+directly into the ``models.py`` of a GeoDjango application::
+
+    # This is an auto-generated Django model module created by ogrinspect.
+    from django.contrib.gis.db import models
+
+    class WorldBorders(models.Model):
+        fips = models.CharField(max_length=2)
+        iso2 = models.CharField(max_length=2)
+        iso3 = models.CharField(max_length=3)
+        un = models.IntegerField()
+        name = models.CharField(max_length=50)
+        area = models.IntegerField()
+        pop2005 = models.IntegerField()
+        region = models.IntegerField()
+        subregion = models.IntegerField()
+        lon = models.FloatField()
+        lat = models.FloatField()
+        geom = models.MultiPolygonField(srid=4326)
+        objects = models.GeoManager()
+
+    # Auto-generated `LayerMapping` dictionary for WorldBorders model
+    worldborders_mapping = {
+        'fips' : 'FIPS',
+        'iso2' : 'ISO2',
+        'iso3' : 'ISO3',
+        'un' : 'UN',
+        'name' : 'NAME',
+        'area' : 'AREA',
+        'pop2005' : 'POP2005',
+        'region' : 'REGION',
+        'subregion' : 'SUBREGION',
+        'lon' : 'LON',
+        'lat' : 'LAT',
+        'geom' : 'MULTIPOLYGON',
+    }
+
+Spatial Queries
+===============
+
+Spatial Lookups
+---------------
+GeoDjango extends the Django ORM and allows the use of spatial lookups.
+Let's do an example where we find the ``WorldBorder`` model that contains
+a point.  First, fire up the management shell::
+
+    $ python manage.py shell
+
+Now, define a point of interest [#]_::
+
+    >>> pnt_wkt = 'POINT(-95.3385 29.7245)'
+
+The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude,
+and 29.7245 degrees latitude.  The geometry is in a format known as
+Well Known Text (WKT), an open standard issued by the Open Geospatial
+Consortium (OGC). [#]_  Import the ``WorldBorders`` model, and perform
+a ``contains`` lookup using the ``pnt_wkt`` as the parameter::
+
+    >>> from world.models import WorldBorders
+    >>> qs = WorldBorders.objects.filter(mpoly__contains=pnt_wkt)
+    >>> qs
+    [<WorldBorders: United States>]
+
+Here we retrieved a ``GeoQuerySet`` that has only one model: the one
+for the United States (which is what we would expect).  Similarly,
+a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the ``intersects``
+spatial lookup is combined with the ``get`` method to retrieve
+only the ``WorldBorders`` instance for San Marino instead of a queryset::
+
+    >>> from django.contrib.gis.geos import Point
+    >>> pnt = Point(12.4604, 43.9420)
+    >>> sm = WorldBorders.objects.get(mpoly__intersects=pnt)
+    >>> sm
+    <WorldBorders: San Marino>
+
+The ``contains`` and ``intersects`` lookups are just a subset of what's
+available -- the :ref:`ref-gis-db-api` documentation has more.
+
+Automatic Spatial Transformations
+---------------------------------
+When querying the spatial database GeoDjango automatically transforms
+geometries if they're in a different coordinate system.  In the following
+example, the coordinate will be expressed in terms of `EPSG SRID 32140`__,
+a coordinate system specific to south Texas **only** and in units of
+**meters** and not degrees::
+
+    >>> from django.contrib.gis.geos import *
+    >>> pnt = Point(954158.1, 4215137.1, srid=32140)
+
+Note that ``pnt`` may also constructed with EWKT, an "extended" form of
+WKT that includes the SRID::
+
+    >>> pnt = GEOSGeometry('SRID=32140;POINT(954158.1 4215137.1)')
+
+When using GeoDjango's ORM, it will automatically wrap geometry values
+in transformation SQL, allowing the developer to work at a higher level
+of abstraction::
+
+    >>> qs = WorldBorders.objects.filter(mpoly__intersects=pnt)
+    >>> qs.query.as_sql() # Generating the SQL
+    ('SELECT "world_worldborders"."id", "world_worldborders"."name", "world_worldborders"."area",
+    "world_worldborders"."pop2005", "world_worldborders"."fips", "world_worldborders"."iso2",
+    "world_worldborders"."iso3", "world_worldborders"."un", "world_worldborders"."region",
+    "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat",
+    "world_worldborders"."mpoly" FROM "world_worldborders"
+    WHERE ST_Intersects("world_worldborders"."mpoly", ST_Transform(%s, 4326))',
+    (<django.contrib.gis.db.backend.postgis.adaptor.PostGISAdaptor object at 0x25641b0>,))
+    >>> qs # printing evaluates the queryset
+    [<WorldBorders: United States>]
+
+__ http://spatialreference.org/ref/epsg/32140/
+
+Lazy Geometries
+---------------
+Geometries come to GeoDjango in a standardized textual representation.  Upon
+access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`,
+exposing powerful functionality, such as serialization properties for
+popular geospatial formats::
+
+    >>> sm = WorldBorders.objects.get(name='San Marino')
+    >>> sm.mpoly
+    <MultiPolygon object at 0x24c6798>
+    >>> sm.mpoly.wkt # WKT
+    MULTIPOLYGON (((12.4157980000000006 43.9579540000000009, 12.4505540000000003 43.9797209999999978, ...
+    >>> sm.mpoly.wkb # WKB (as Python binary buffer)
+    <read-only buffer for 0x1fe2c70, size -1, offset 0 at 0x2564c40>
+    >>> sm.mpoly.geojson # GeoJSON (requires GDAL)
+    '{ "type": "MultiPolygon", "coordinates": [ [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ...
+
+This includes access to all of the advanced geometric operations provided by
+the GEOS library::
+
+    >>> pnt = Point(12.4604, 43.9420)
+    >>> sm.mpoly.contains(pnt)
+    True
+    >>> pnt.contains(sm.mpoly)
+    False
+
+``GeoQuerySet`` Methods
+-----------------------
+
+
+Putting your data on the map
+============================
+
+Google
+------
+
+Geographic Admin
+----------------
+
+GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>`
+to enable support for editing geometry fields.
+
+Basics
+^^^^^^
+
+GeoDjango also supplements the Django admin by allowing users to create
+and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_).
+
+Let's dive in again -- create a file called ``admin.py`` inside the
+``world`` application, and insert the following::
+
+    from django.contrib.gis import admin
+    from models import WorldBorders
+
+    admin.site.register(WorldBorders, admin.GeoModelAdmin)
+
+Next, edit your ``urls.py`` in the ``geodjango`` project folder to look
+as follows::
+
+    from django.conf.urls.defaults import *
+    from django.contrib.gis import admin
+
+    admin.autodiscover()
+
+    urlpatterns = patterns('',
+        (r'^admin/', include(admin.site.urls)),
+    )
+
+Start up the Django development server::
+
+    $ python manage.py runserver
+
+Finally, browse to ``http://localhost:8000/admin/``, and log in with the admin
+user created after running ``syncdb``.  Browse to any of the ``WorldBorders``
+entries -- the borders may be edited by clicking on a polygon and dragging
+the vertexes to the desired position.
+
+.. _OpenLayers: http://openlayers.org/
+.. _Open Street Map: http://openstreetmap.org/
+.. _Vector Map Level 0: http://earth-info.nga.mil/publications/vmap0.html
+.. _Metacarta: http://metacarta.com
+
+.. _osmgeoadmin-intro:
+
+``OSMGeoAdmin``
+^^^^^^^^^^^^^^^
+
+With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses
+a `Open Street Map`_ layer in the admin.
+This provides more context (including street and thoroughfare details) than
+available with the :class:`~django.contrib.gis.admin.GeoModelAdmin`
+(which uses the `Vector Map Level 0`_ WMS data set hosted at `Metacarta`_).
+
+First, there are some important requirements and limitations:
+
+* :class:`~django.contrib.gis.admin.OSMGeoAdmin` requires that the
+  :ref:`spherical mercator projection be added <addgoogleprojection>`
+  to the to be added to the ``spatial_ref_sys`` table (PostGIS 1.3 and
+  below, only).
+* The PROJ.4 datum shifting files must be installed (see the
+  :ref:`PROJ.4 installation instructions <proj4>` for more details).
+
+If you meet these requirements, then just substitute in the ``OSMGeoAdmin``
+option class in your ``admin.py`` file::
+
+    admin.site.register(WorldBorders, admin.OSMGeoAdmin)
+
+.. rubric:: Footnotes
+
+.. [#] Special thanks to Bjørn Sandvik of `thematicmapping.org <http://thematicmapping.org>`_ for providing and maintaining this data set.
+.. [#] GeoDjango basic apps was written by Dane Springmeyer, Josh Livni, and Christopher Schmidt.
+.. [#] Here the point is for the `University of Houston Law Center <http://www.law.uh.edu/>`_ .
+.. [#] Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049.
diff --git a/parts/django/docs/ref/contrib/gis/utils.txt b/parts/django/docs/ref/contrib/gis/utils.txt
new file mode 100644
index 0000000..9f8e518
--- /dev/null
+++ b/parts/django/docs/ref/contrib/gis/utils.txt
@@ -0,0 +1,32 @@
+.. _ref-gis-utils:
+
+===================
+GeoDjango Utilities
+===================
+
+.. module:: django.contrib.gis.utils
+   :synopsis: GeoDjango's collection of utilities.
+
+The :mod:`django.contrib.gis.utils` module contains various utilities that are
+useful in creating geospatial Web applications.
+
+.. toctree::
+   :maxdepth: 2
+
+   geoip
+   layermapping
+   ogrinspect
+
+GeoIP
+=====
+
+Interface to the MaxMind GeoIP library for performing IP-based geolocation
+from GeoDjango.  See :ref:`GeoIP reference <ref-geoip>` documentation for
+more information.
+
+LayerMapping
+============
+
+The :class:`~django.contrib.gis.utils.LayerMapping` simplifies the process
+of importing spatial data and attributes into your GeoDjango models.
+
diff --git a/parts/django/docs/ref/contrib/humanize.txt b/parts/django/docs/ref/contrib/humanize.txt
new file mode 100644
index 0000000..b5ec518
--- /dev/null
+++ b/parts/django/docs/ref/contrib/humanize.txt
@@ -0,0 +1,100 @@
+========================
+django.contrib.humanize
+========================
+
+.. module:: django.contrib.humanize
+   :synopsis: A set of Django template filters useful for adding a "human
+              touch" to data.
+
+A set of Django template filters useful for adding a "human touch" to data.
+
+To activate these filters, add ``'django.contrib.humanize'`` to your
+:setting:`INSTALLED_APPS` setting. Once you've done that, use
+``{% load humanize %}`` in a template, and you'll have access to the following
+filters.
+
+.. templatefilter:: apnumber
+
+apnumber
+--------
+
+For numbers 1-9, returns the number spelled out. Otherwise, returns the
+number. This follows Associated Press style.
+
+Examples:
+
+    * ``1`` becomes ``one``.
+    * ``2`` becomes ``two``.
+    * ``10`` becomes ``10``.
+
+You can pass in either an integer or a string representation of an integer.
+
+.. templatefilter:: intcomma
+
+intcomma
+--------
+
+Converts an integer to a string containing commas every three digits.
+
+Examples:
+
+    * ``4500`` becomes ``4,500``.
+    * ``45000`` becomes ``45,000``.
+    * ``450000`` becomes ``450,000``.
+    * ``4500000`` becomes ``4,500,000``.
+
+You can pass in either an integer or a string representation of an integer.
+
+.. templatefilter:: intword
+
+intword
+-------
+
+Converts a large integer to a friendly text representation. Works best for
+numbers over 1 million.
+
+Examples:
+
+    * ``1000000`` becomes ``1.0 million``.
+    * ``1200000`` becomes ``1.2 million``.
+    * ``1200000000`` becomes ``1.2 billion``.
+
+Values up to 1000000000000000 (one quadrillion) are supported.
+
+You can pass in either an integer or a string representation of an integer.
+
+.. templatefilter:: naturalday
+
+naturalday
+----------
+
+.. versionadded:: 1.0
+
+For dates that are the current day or within one day, return "today",
+"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
+the passed in format string.
+
+**Argument:** Date formatting string as described in the :tfilter:`date` tag.
+
+Examples (when 'today' is 17 Feb 2007):
+
+    * ``16 Feb 2007`` becomes ``yesterday``.
+    * ``17 Feb 2007`` becomes ``today``.
+    * ``18 Feb 2007`` becomes ``tomorrow``.
+    * Any other day is formatted according to given argument or the
+      :setting:`DATE_FORMAT` setting if no argument is given.
+
+.. templatefilter:: ordinal
+
+ordinal
+-------
+
+Converts an integer to its ordinal as a string.
+
+Examples:
+
+    * ``1`` becomes ``1st``.
+    * ``2`` becomes ``2nd``.
+    * ``3`` becomes ``3rd``.
+
+You can pass in either an integer or a string representation of an integer.
diff --git a/parts/django/docs/ref/contrib/index.txt b/parts/django/docs/ref/contrib/index.txt
new file mode 100644
index 0000000..90edf72
--- /dev/null
+++ b/parts/django/docs/ref/contrib/index.txt
@@ -0,0 +1,207 @@
+====================
+``contrib`` packages
+====================
+
+Django aims to follow Python's `"batteries included" philosophy`_. It ships
+with a variety of extra, optional tools that solve common Web-development
+problems.
+
+This code lives in ``django/contrib`` in the Django distribution. This document
+gives a rundown of the packages in ``contrib``, along with any dependencies
+those packages have.
+
+.. admonition:: Note
+
+    For most of these add-ons -- specifically, the add-ons that include either
+    models or template tags -- you'll need to add the package name (e.g.,
+    ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run
+    ``manage.py syncdb``.
+
+.. _"batteries included" philosophy: http://docs.python.org/tutorial/stdlib.html#batteries-included
+
+.. toctree::
+   :maxdepth: 1
+
+   admin/index
+   auth
+   comments/index
+   contenttypes
+   csrf
+   databrowse
+   flatpages
+   formtools/index
+   gis/index
+   humanize
+   localflavor
+   markup
+   messages
+   redirects
+   sitemaps
+   sites
+   syndication
+   webdesign
+
+admin
+=====
+
+The automatic Django administrative interface. For more information, see
+:doc:`Tutorial 2 </intro/tutorial02>` and the
+:doc:`admin documentation </ref/contrib/admin/index>`.
+
+Requires the auth_ and contenttypes_ contrib packages to be installed.
+
+auth
+====
+
+Django's authentication framework.
+
+See :doc:`/topics/auth`.
+
+comments
+========
+
+.. versionchanged:: 1.0
+   The comments application has been rewriten. See :doc:`/ref/contrib/comments/upgrade`
+   for information on howto upgrade.
+
+A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`.
+
+contenttypes
+============
+
+A light framework for hooking into "types" of content, where each installed
+Django model is a separate content type.
+
+See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`.
+
+csrf
+====
+
+A middleware for preventing Cross Site Request Forgeries
+
+See the :doc:`csrf documentation </ref/contrib/csrf>`.
+
+flatpages
+=========
+
+A framework for managing simple "flat" HTML content in a database.
+
+See the :doc:`flatpages documentation </ref/contrib/flatpages>`.
+
+Requires the sites_ contrib package to be installed as well.
+
+formtools
+=========
+
+A set of high-level abstractions for Django forms (django.forms).
+
+django.contrib.formtools.preview
+--------------------------------
+
+An abstraction of the following workflow:
+
+"Display an HTML form, force a preview, then do something with the submission."
+
+See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`.
+
+django.contrib.formtools.wizard
+--------------------------------
+
+Splits forms across multiple Web pages.
+
+See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`.
+
+gis
+====
+
+A world-class geospatial framework built on top of Django, that enables
+storage, manipulation and display of spatial data.
+
+See the :doc:`/ref/contrib/gis/index` documentation for more.
+
+humanize
+========
+
+A set of Django template filters useful for adding a "human touch" to data.
+
+See the :doc:`humanize documentation </ref/contrib/humanize>`.
+
+localflavor
+===========
+
+A collection of various Django snippets that are useful only for a particular
+country or culture. For example, ``django.contrib.localflavor.us.forms``
+contains a ``USZipCodeField`` that you can use to validate U.S. zip codes.
+
+See the :doc:`localflavor documentation </ref/contrib/localflavor>`.
+
+markup
+======
+
+A collection of template filters that implement common markup languages
+
+See the :doc:`markup documentation </ref/contrib/markup>`.
+
+messages
+========
+
+.. versionchanged:: 1.2
+    The messages framework was added.
+
+A framework for storing and retrieving temporary cookie- or session-based
+messages
+
+See the :doc:`messages documentation </ref/contrib/messages>`.
+
+redirects
+=========
+
+A framework for managing redirects.
+
+See the :doc:`redirects documentation </ref/contrib/redirects>`.
+
+sessions
+========
+
+A framework for storing data in anonymous sessions.
+
+See the :doc:`sessions documentation </topics/http/sessions>`.
+
+sites
+=====
+
+A light framework that lets you operate multiple Web sites off of the same
+database and Django installation. It gives you hooks for associating objects to
+one or more sites.
+
+See the :doc:`sites documentation </ref/contrib/sites>`.
+
+sitemaps
+========
+
+A framework for generating Google sitemap XML files.
+
+See the :doc:`sitemaps documentation </ref/contrib/sitemaps>`.
+
+syndication
+===========
+
+A framework for generating syndication feeds, in RSS and Atom, quite easily.
+
+See the :doc:`syndication documentation </ref/contrib/syndication>`.
+
+webdesign
+=========
+
+Helpers and utilities targeted primarily at Web *designers* rather than
+Web *developers*.
+
+See the :doc:`Web design helpers documentation </ref/contrib/webdesign>`.
+
+Other add-ons
+=============
+
+If you have an idea for functionality to include in ``contrib``, let us know!
+Code it up, and post it to the `django-users mailing list`_.
+
+.. _django-users mailing list: http://groups.google.com/group/django-users
diff --git a/parts/django/docs/ref/contrib/localflavor.txt b/parts/django/docs/ref/contrib/localflavor.txt
new file mode 100644
index 0000000..2eb731d
--- /dev/null
+++ b/parts/django/docs/ref/contrib/localflavor.txt
@@ -0,0 +1,842 @@
+==========================
+The "local flavor" add-ons
+==========================
+
+.. module:: django.contrib.localflavor
+    :synopsis: A collection of various Django snippets that are useful only for
+               a particular country or culture.
+
+Following its "batteries included" philosophy, Django comes with assorted
+pieces of code that are useful for particular countries or cultures. These are
+called the "local flavor" add-ons and live in the
+:mod:`django.contrib.localflavor` package.
+
+Inside that package, country- or culture-specific code is organized into
+subpackages, named using `ISO 3166 country codes`_.
+
+Most of the ``localflavor`` add-ons are localized form components deriving
+from the :doc:`forms </topics/forms/index>` framework -- for example, a
+:class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to
+validate U.S. state abbreviations, and a
+:class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that
+knows how to validate Finnish social security numbers.
+
+To use one of these localized components, just import the relevant subpackage.
+For example, here's how you can create a form with a field representing a
+French telephone number::
+
+    from django import forms
+    from django.contrib.localflavor.fr.forms import FRPhoneNumberField
+
+    class MyForm(forms.Form):
+        my_french_phone_no = FRPhoneNumberField()
+
+Supported countries
+===================
+
+Countries currently supported by :mod:`~django.contrib.localflavor` are:
+
+    * Argentina_
+    * Australia_
+    * Austria_
+    * Brazil_
+    * Canada_
+    * Chile_
+    * Czech_
+    * Finland_
+    * France_
+    * Germany_
+    * Iceland_
+    * India_
+    * Indonesia_
+    * Ireland_
+    * Italy_
+    * Japan_
+    * Kuwait_
+    * Mexico_
+    * `The Netherlands`_
+    * Norway_
+    * Peru_
+    * Poland_
+    * Portugal_
+    * Romania_
+    * Slovakia_
+    * `South Africa`_
+    * Spain_
+    * Sweden_
+    * Switzerland_
+    * `United Kingdom`_
+    * `United States of America`_
+    * Uruguay_
+
+The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage,
+containing useful code that is not specific to one particular country or culture.
+Currently, it defines date, datetime and split datetime input fields based on
+those from :doc:`forms </topics/forms/index>`, but with non-US default formats.
+Here's an example of how to use them::
+
+    from django import forms
+    from django.contrib.localflavor import generic
+
+    class MyForm(forms.Form):
+        my_date_field = generic.forms.DateField()
+
+.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
+.. _Argentina: `Argentina (ar)`_
+.. _Australia: `Australia (au)`_
+.. _Austria: `Austria (at)`_
+.. _Brazil: `Brazil (br)`_
+.. _Canada: `Canada (ca)`_
+.. _Chile: `Chile (cl)`_
+.. _Czech: `Czech (cz)`_
+.. _Finland: `Finland (fi)`_
+.. _France: `France (fr)`_
+.. _Germany: `Germany (de)`_
+.. _The Netherlands: `The Netherlands (nl)`_
+.. _Iceland: `Iceland (is\_)`_
+.. _India: `India (in\_)`_
+.. _Indonesia: `Indonesia (id)`_
+.. _Ireland: `Ireland (ie)`_
+.. _Italy: `Italy (it)`_
+.. _Japan: `Japan (jp)`_
+.. _Kuwait: `Kuwait (kw)`_
+.. _Mexico: `Mexico (mx)`_
+.. _Norway: `Norway (no)`_
+.. _Peru: `Peru (pe)`_
+.. _Poland: `Poland (pl)`_
+.. _Portugal: `Portugal (pt)`_
+.. _Romania: `Romania (ro)`_
+.. _Slovakia: `Slovakia (sk)`_
+.. _South Africa: `South Africa (za)`_
+.. _Spain: `Spain (es)`_
+.. _Sweden: `Sweden (se)`_
+.. _Switzerland: `Switzerland (ch)`_
+.. _United Kingdom: `United Kingdom (uk)`_
+.. _United States of America: `United States of America (us)`_
+.. _Uruguay: `Uruguay (uy)`_
+
+Adding flavors
+==============
+
+We'd love to add more of these to Django, so please `create a ticket`_ with
+any code you'd like to contribute. One thing we ask is that you please use
+Unicode objects (``u'mystring'``) for strings, rather than setting the encoding
+in the file. See any of the existing flavors for examples.
+
+.. _create a ticket: http://code.djangoproject.com/simpleticket
+
+Argentina (``ar``)
+=============================================
+
+.. class:: ar.forms.ARPostalCodeField
+
+    A form field that validates input as either a classic four-digit Argentinian
+    postal code or a CPA_.
+
+.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php
+
+.. class:: ar.forms.ARDNIField
+
+    A form field that validates input as a Documento Nacional de Identidad (DNI)
+    number.
+
+.. class:: ar.forms.ARCUITField
+
+    A form field that validates input as a Codigo Unico de Identificacion
+    Tributaria (CUIT) number.
+
+.. class:: ar.forms.ARProvinceSelect
+
+    A ``Select`` widget that uses a list of Argentina's provinces and autonomous
+    cities as its choices.
+
+Australia (``au``)
+=============================================
+
+.. class:: au.forms.AUPostCodeField
+
+    A form field that validates input as an Australian postcode.
+
+.. class:: au.forms.AUPhoneNumberField
+
+    A form field that validates input as an Australian phone number. Valid numbers
+    have ten digits.
+
+.. class:: au.forms.AUStateSelect
+
+    A ``Select`` widget that uses a list of Australian states/territories as its
+    choices.
+
+Austria (``at``)
+================
+
+.. class:: at.forms.ATZipCodeField
+
+    A form field that validates its input as an Austrian zip code.
+
+.. class:: at.forms.ATStateSelect
+
+    A ``Select`` widget that uses a list of Austrian states as its choices.
+
+.. class:: at.forms.ATSocialSecurityNumberField
+
+    A form field that validates its input as an Austrian social security number.
+
+Brazil (``br``)
+===============
+
+.. class:: br.forms.BRPhoneNumberField
+
+    A form field that validates input as a Brazilian phone number, with the format
+    XX-XXXX-XXXX.
+
+.. class:: br.forms.BRZipCodeField
+
+    A form field that validates input as a Brazilian zip code, with the format
+    XXXXX-XXX.
+
+.. class:: br.forms.BRStateSelect
+
+    A ``Select`` widget that uses a list of Brazilian states/territories as its
+    choices.
+
+.. class:: br.forms.BRCPFField
+
+    A form field that validates input as `Brazilian CPF`_.
+    
+    Input can either be of the format XXX.XXX.XXX-VD or be a group of 11 digits.
+
+.. _Brazilian CPF: http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas
+
+.. class:: br.forms.BRCNPJField
+
+    A form field that validates input as `Brazilian CNPJ`_.
+    
+    Input can either be of the format XX.XXX.XXX/XXXX-XX or be a group of 14
+    digits.
+
+.. _Brazilian CNPJ: http://en.wikipedia.org/wiki/National_identification_number#Brazil
+
+Canada (``ca``)
+===============
+
+.. class:: ca.forms.CAPhoneNumberField
+
+    A form field that validates input as a Canadian phone number, with the format
+    XXX-XXX-XXXX.
+
+.. class:: ca.forms.CAPostalCodeField
+
+    A form field that validates input as a Canadian postal code, with the format
+    XXX XXX.
+
+.. class:: ca.forms.CAProvinceField
+
+    A form field that validates input as a Canadian province name or abbreviation.
+
+.. class:: ca.forms.CASocialInsuranceNumberField
+
+    A form field that validates input as a Canadian Social Insurance Number (SIN).
+    A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10
+    checksum`_.
+
+.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm
+
+.. class:: ca.forms.CAProvinceSelect
+
+    A ``Select`` widget that uses a list of Canadian provinces and territories as
+    its choices.
+
+Chile (``cl``)
+==============
+
+.. class:: cl.forms.CLRutField
+
+    A form field that validates input as a Chilean national identification number
+    ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X.
+
+.. class:: cl.forms.CLRegionSelect
+
+    A ``Select`` widget that uses a list of Chilean regions (Regiones) as its
+    choices.
+
+Czech (``cz``)
+==============
+
+.. class:: cz.forms.CZPostalCodeField
+
+    A form field that validates input as a Czech postal code. Valid formats
+    are XXXXX or XXX XX, where X is a digit.
+
+.. class:: cz.forms.CZBirthNumberField
+
+    A form field that validates input as a Czech Birth Number.
+    A valid number must be in format XXXXXX/XXXX (slash is optional).
+
+.. class:: cz.forms.CZICNumberField
+
+    A form field that validates input as a Czech IC number field.
+
+.. class:: cz.forms.CZRegionSelect
+
+    A ``Select`` widget that uses a list of Czech regions as its choices.
+
+Finland (``fi``)
+================
+
+.. class:: fi.forms.FISocialSecurityNumber
+
+    A form field that validates input as a Finnish social security number.
+
+.. class:: fi.forms.FIZipCodeField
+
+    A form field that validates input as a Finnish zip code. Valid codes
+    consist of five digits.
+
+.. class:: fi.forms.FIMunicipalitySelect
+
+    A ``Select`` widget that uses a list of Finnish municipalities as its
+    choices.
+
+France (``fr``)
+===============
+
+.. class:: fr.forms.FRPhoneNumberField
+
+    A form field that validates input as a French local phone number. The
+    correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate
+    but are corrected to 0X XX XX XX XX.
+
+.. class:: fr.forms.FRZipCodeField
+
+    A form field that validates input as a French zip code. Valid codes
+    consist of five digits.
+
+.. class:: fr.forms.FRDepartmentSelect
+
+    A ``Select`` widget that uses a list of French departments as its choices.
+
+Germany (``de``)
+================
+
+.. class:: de.forms.DEIdentityCardNumberField
+
+    A form field that validates input as a German identity card number
+    (Personalausweis_). Valid numbers have the format
+    XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes.
+
+.. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis
+
+.. class:: de.forms.DEZipCodeField
+
+    A form field that validates input as a German zip code. Valid codes
+    consist of five digits.
+
+.. class:: de.forms.DEStateSelect
+
+    A ``Select`` widget that uses a list of German states as its choices.
+
+The Netherlands (``nl``)
+========================
+
+.. class:: nl.forms.NLPhoneNumberField
+
+    A form field that validates input as a Dutch telephone number.
+
+.. class:: nl.forms.NLSofiNumberField
+
+    A form field that validates input as a Dutch social security number
+    (SoFI/BSN).
+
+.. class:: nl.forms.NLZipCodeField
+
+    A form field that validates input as a Dutch zip code.
+
+.. class:: nl.forms.NLProvinceSelect
+
+    A ``Select`` widget that uses a list of Dutch provinces as its list of
+    choices.
+
+Iceland (``is_``)
+=================
+
+.. class:: is_.forms.ISIdNumberField
+
+    A form field that validates input as an Icelandic identification number
+    (kennitala). The format is XXXXXX-XXXX.
+
+.. class:: is_.forms.ISPhoneNumberField
+
+    A form field that validates input as an Icelandtic phone number (seven
+    digits with an optional hyphen or space after the first three digits).
+
+.. class:: is_.forms.ISPostalCodeSelect
+
+    A ``Select`` widget that uses a list of Icelandic postal codes as its
+    choices.
+
+India (``in_``)
+===============
+
+.. class:: in.forms.INStateField
+
+    A form field that validates input as an Indian state/territory name or
+    abbreviation. Input is normalized to the standard two-letter vehicle
+    registration abbreviation for the given state or territory.
+
+.. class:: in.forms.INZipCodeField
+
+    A form field that validates input as an Indian zip code, with the
+    format XXXXXXX.
+
+.. class:: in.forms.INStateSelect
+
+    A ``Select`` widget that uses a list of Indian states/territories as its
+    choices.
+
+Ireland (``ie``)
+================
+
+.. class:: ie.forms.IECountySelect
+
+    A ``Select`` widget that uses a list of Irish Counties as its choices.
+
+Indonesia (``id``)
+==================
+
+.. class:: id.forms.IDPostCodeField
+
+    A form field that validates input as an Indonesian post code field.
+
+.. class:: id.forms.IDProvinceSelect
+
+    A ``Select`` widget that uses a list of Indonesian provinces as its choices.
+
+.. class:: id.forms.IDPhoneNumberField
+
+    A form field that validates input as an Indonesian telephone number.
+
+.. class:: id.forms.IDLicensePlatePrefixSelect
+
+    A ``Select`` widget that uses a list of Indonesian license plate
+    prefix code as its choices.
+
+.. class:: id.forms.IDLicensePlateField
+
+    A form field that validates input as an Indonesian vehicle license plate.
+
+.. class:: id.forms.IDNationalIdentityNumberField
+
+    A form field that validates input as an Indonesian national identity
+    number (`NIK`_/KTP). The output will be in the format of
+    'XX.XXXX.DDMMYY.XXXX'. Dots or spaces can be used in the input to break
+    down the numbers.
+
+.. _NIK: http://en.wikipedia.org/wiki/Indonesian_identity_card
+
+Italy (``it``)
+==============
+
+.. class:: it.forms.ITSocialSecurityNumberField
+
+    A form field that validates input as an Italian social security number
+    (`codice fiscale`_).
+
+.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche
+
+.. class:: it.forms.ITVatNumberField
+
+    A form field that validates Italian VAT numbers (partita IVA).
+
+.. class:: it.forms.ITZipCodeField
+
+    A form field that validates input as an Italian zip code. Valid codes
+    must have five digits.
+
+.. class:: it.forms.ITProvinceSelect
+
+    A ``Select`` widget that uses a list of Italian provinces as its choices.
+
+.. class:: it.forms.ITRegionSelect
+
+    A ``Select`` widget that uses a list of Italian regions as its choices.
+
+Japan (``jp``)
+==============
+
+.. class:: jp.forms.JPPostalCodeField
+
+    A form field that validates input as a Japanese postcode. It accepts seven
+    digits, with or without a hyphen.
+
+.. class:: jp.forms.JPPrefectureSelect
+
+    A ``Select`` widget that uses a list of Japanese prefectures as its choices.
+
+Kuwait (``kw``)
+===============
+
+.. class:: kw.forms.KWCivilIDNumberField
+
+    A form field that validates input as a Kuwaiti Civil ID number. A valid
+    Civil ID number must obey the following rules:
+
+    * The number consist of 12 digits.
+    * The birthdate of the person is a valid date.
+    * The calculated checksum equals to the last digit of the Civil ID.
+
+Mexico (``mx``)
+===============
+
+.. class:: mx.forms.MXStateSelect
+
+    A ``Select`` widget that uses a list of Mexican states as its choices.
+
+Norway (``no``)
+===============
+
+.. class:: no.forms.NOSocialSecurityNumber
+
+    A form field that validates input as a Norwegian social security number
+    (personnummer_).
+
+.. _personnummer: http://no.wikipedia.org/wiki/Personnummer
+
+.. class:: no.forms.NOZipCodeField
+
+    A form field that validates input as a Norwegian zip code. Valid codes
+    have four digits.
+
+.. class:: no.forms.NOMunicipalitySelect
+
+    A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as
+    its choices.
+
+Peru (``pe``)
+=============
+
+.. class:: pe.forms.PEDNIField
+
+    A form field that validates input as a DNI (Peruvian national identity)
+    number.
+
+.. class:: pe.forms.PERUCField
+
+    A form field that validates input as an RUC (Registro Unico de
+    Contribuyentes) number. Valid RUC numbers have 11 digits.
+
+.. class:: pe.forms.PEDepartmentSelect
+
+    A ``Select`` widget that uses a list of Peruvian Departments as its choices.
+
+Poland (``pl``)
+===============
+
+.. class:: pl.forms.PLPESELField
+
+    A form field that validates input as a Polish national identification number
+    (PESEL_).
+
+.. _PESEL: http://en.wikipedia.org/wiki/PESEL
+
+.. class:: pl.forms.PLREGONField
+
+    A form field that validates input as a Polish National Official Business
+    Register Number (REGON_), having either seven or nine digits. The checksum
+    algorithm used for REGONs is documented at
+    http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
+
+.. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm
+
+.. class:: pl.forms.PLPostalCodeField
+
+    A form field that validates input as a Polish postal code. The valid format
+    is XX-XXX, where X is a digit.
+
+.. class:: pl.forms.PLNIPField
+
+    A form field that validates input as a Polish Tax Number (NIP). Valid
+    formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used
+    for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html.
+
+.. class:: pl.forms.PLCountySelect
+
+    A ``Select`` widget that uses a list of Polish administrative units as its
+    choices.
+
+.. class:: pl.forms.PLProvinceSelect
+
+    A ``Select`` widget that uses a list of Polish voivodeships (administrative
+    provinces) as its choices.
+
+Portugal (``pt``)
+=================
+
+.. class:: pt.forms.PTZipCodeField
+
+    A form field that validates input as a Portuguese zip code.
+
+.. class:: pt.forms.PTPhoneNumberField
+
+    A form field that validates input as a Portuguese phone number.
+    Valid numbers have 9 digits (may include spaces) or start by 00
+    or + (international).
+
+Romania (``ro``)
+================
+
+.. class:: ro.forms.ROCIFField
+
+    A form field that validates Romanian fiscal identification codes (CIF). The
+    return value strips the leading RO, if given.
+
+.. class:: ro.forms.ROCNPField
+
+    A form field that validates Romanian personal numeric codes (CNP).
+
+.. class:: ro.forms.ROCountyField
+
+    A form field that validates its input as a Romanian county (judet) name or
+    abbreviation. It normalizes the input to the standard vehicle registration
+    abbreviation for the given county. This field will only accept names written
+    with diacritics; consider using ROCountySelect as an alternative.
+
+.. class:: ro.forms.ROCountySelect
+
+    A ``Select`` widget that uses a list of Romanian counties (judete) as its
+    choices.
+
+.. class:: ro.forms.ROIBANField
+
+    A form field that validates its input as a Romanian International Bank
+    Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX,
+    with or without hyphens.
+
+.. class:: ro.forms.ROPhoneNumberField
+
+    A form field that validates Romanian phone numbers, short special numbers
+    excluded.
+
+.. class:: ro.forms.ROPostalCodeField
+
+    A form field that validates Romanian postal codes.
+
+Slovakia (``sk``)
+=================
+
+.. class:: sk.forms.SKPostalCodeField
+
+    A form field that validates input as a Slovak postal code. Valid formats
+    are XXXXX or XXX XX, where X is a digit.
+
+.. class:: sk.forms.SKDistrictSelect
+
+    A ``Select`` widget that uses a list of Slovak districts as its choices.
+
+.. class:: sk.forms.SKRegionSelect
+
+    A ``Select`` widget that uses a list of Slovak regions as its choices.
+
+South Africa (``za``)
+=====================
+
+.. class:: za.forms.ZAIDField
+
+    A form field that validates input as a South African ID number. Validation
+    uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check
+    for birth date.
+
+.. class:: za.forms.ZAPostCodeField
+
+    A form field that validates input as a South African postcode. Valid
+    postcodes must have four digits.
+
+Spain (``es``)
+==============
+
+.. class:: es.forms.ESIdentityCardNumberField
+
+    A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal
+    Identification Number) code.
+
+.. class:: es.forms.ESCCCField
+
+    A form field that validates input as a Spanish bank account number (Codigo
+    Cuenta Cliente or CCC). A valid CCC number has the format
+    EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity,
+    office, checksum and account, respectively. The first checksum digit
+    validates the entity and office. The second checksum digit validates the
+    account. It is also valid to use a space as a delimiter, or to use no
+    delimiter.
+
+.. class:: es.forms.ESPhoneNumberField
+
+    A form field that validates input as a Spanish phone number. Valid numbers
+    have nine digits, the first of which is 6, 8 or 9.
+
+.. class:: es.forms.ESPostalCodeField
+
+    A form field that validates input as a Spanish postal code. Valid codes
+    have five digits, the first two being in the range 01 to 52, representing
+    the province.
+
+.. class:: es.forms.ESProvinceSelect
+
+    A ``Select`` widget that uses a list of Spanish provinces as its choices.
+
+.. class:: es.forms.ESRegionSelect
+
+    A ``Select`` widget that uses a list of Spanish regions as its choices.
+
+Sweden (``se``)
+===============
+
+.. class:: se.forms.SECountySelect
+
+    A Select form widget that uses a list of the Swedish counties (län) as its
+    choices.
+
+    The cleaned value is the official county code -- see
+    http://en.wikipedia.org/wiki/Counties_of_Sweden for a list.
+
+.. class:: se.forms.SEOrganisationNumber
+
+    A form field that validates input as a Swedish organisation number
+    (organisationsnummer).
+
+    It accepts the same input as SEPersonalIdentityField (for sole
+    proprietorships (enskild firma). However, co-ordination numbers are not
+    accepted.
+
+    It also accepts ordinary Swedish organisation numbers with the format
+    NNNNNNNNNN.
+
+    The return value will be YYYYMMDDXXXX for sole proprietors, and NNNNNNNNNN
+    for other organisations.
+
+.. class:: se.forms.SEPersonalIdentityNumber
+
+    A form field that validates input as a Swedish personal identity number
+    (personnummer).
+
+    The correct formats are YYYYMMDD-XXXX, YYYYMMDDXXXX, YYMMDD-XXXX,
+    YYMMDDXXXX and YYMMDD+XXXX.
+
+    A \+ indicates that the person is older than 100 years, which will be taken
+    into consideration when the date is validated.
+
+    The checksum will be calculated and checked. The birth date is checked
+    to be a valid date.
+
+    By default, co-ordination numbers (samordningsnummer) will be accepted. To
+    only allow real personal identity numbers, pass the keyword argument
+    coordination_number=False to the constructor.
+
+    The cleaned value will always have the format YYYYMMDDXXXX.
+
+.. class:: se.forms.SEPostalCodeField
+
+    A form field that validates input as a Swedish postal code (postnummer).
+    Valid codes consist of five digits (XXXXX). The number can optionally be
+    formatted with a space after the third digit (XXX XX).
+
+    The cleaned value will never contain the space.
+
+Switzerland (``ch``)
+====================
+
+.. class:: ch.forms.CHIdentityCardNumberField
+
+    A form field that validates input as a Swiss identity card number.
+    A valid number must confirm to the X1234567<0 or 1234567890 format and
+    have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm.
+
+.. class:: ch.forms.CHPhoneNumberField
+
+    A form field that validates input as a Swiss phone number. The correct
+    format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are
+    corrected to 0XX XXX XX XX.
+
+.. class:: ch.forms.CHZipCodeField
+
+    A form field that validates input as a Swiss zip code. Valid codes
+    consist of four digits.
+
+.. class:: ch.forms.CHStateSelect
+
+    A ``Select`` widget that uses a list of Swiss states as its choices.
+
+United Kingdom (``uk``)
+=======================
+
+.. class:: uk.forms.UKPostcodeField
+
+    A form field that validates input as a UK postcode. The regular
+    expression used is sourced from the schema for British Standard BS7666
+    address types at http://www.cabinetoffice.gov.uk/media/291293/bs7666-v2-0.xml.
+
+.. class:: uk.forms.UKCountySelect
+
+    A ``Select`` widget that uses a list of UK counties/regions as its choices.
+
+.. class:: uk.forms.UKNationSelect
+
+    A ``Select`` widget that uses a list of UK nations as its choices.
+
+United States of America (``us``)
+=================================
+
+.. class:: us.forms.USPhoneNumberField
+
+    A form field that validates input as a U.S. phone number.
+
+.. class:: us.forms.USSocialSecurityNumberField
+
+    A form field that validates input as a U.S. Social Security Number (SSN).
+    A valid SSN must obey the following rules:
+
+        * Format of XXX-XX-XXXX
+        * No group of digits consisting entirely of zeroes
+        * Leading group of digits cannot be 666
+        * Number not in promotional block 987-65-4320 through 987-65-4329
+        * Number not one known to be invalid due to widespread promotional
+          use or distribution (e.g., the Woolworth's number or the 1962
+          promotional number)
+
+.. class:: us.forms.USStateField
+
+    A form field that validates input as a U.S. state name or abbreviation. It
+    normalizes the input to the standard two-letter postal service abbreviation
+    for the given state.
+
+.. class:: us.forms.USZipCodeField
+
+    A form field that validates input as a U.S. ZIP code. Valid formats are
+    XXXXX or XXXXX-XXXX.
+
+.. class:: us.forms.USStateSelect
+
+    A form ``Select`` widget that uses a list of U.S. states/territories as its
+    choices.
+
+.. class:: us.models.PhoneNumberField
+
+    A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
+    number (in the format ``XXX-XXX-XXXX``).
+
+.. class:: us.models.USStateField
+
+    A model field that forms represent as a ``forms.USStateField`` field and
+    stores the two-letter U.S. state abbreviation in the database.
+
+Uruguay (``uy``)
+================
+
+.. class:: uy.forms.UYCIField
+
+    A field that validates Uruguayan 'Cedula de identidad' (CI) numbers.
+
+.. class:: uy.forms.UYDepartamentSelect
+
+    A ``Select`` widget that uses a list of  Uruguayan departaments as its
+    choices.
diff --git a/parts/django/docs/ref/contrib/markup.txt b/parts/django/docs/ref/contrib/markup.txt
new file mode 100644
index 0000000..9282313
--- /dev/null
+++ b/parts/django/docs/ref/contrib/markup.txt
@@ -0,0 +1,42 @@
+=====================
+django.contrib.markup
+=====================
+
+.. module:: django.contrib.markup
+   :synopsis: A collection of template filters that implement common markup languages.
+
+Django provides template filters that implement the following markup
+languages:
+
+    * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_
+    * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_
+    * ``restructuredtext`` -- implements `reST (reStructured Text)`_
+      -- requires `doc-utils`_
+
+In each case, the filter expects formatted markup as a string and
+returns a string representing the marked-up text. For example, the
+``textile`` filter converts text that is marked-up in Textile format
+to HTML.
+
+To activate these filters, add ``'django.contrib.markup'`` to your
+:setting:`INSTALLED_APPS` setting. Once you've done that, use
+``{% load markup %}`` in a template, and you'll have access to these filters.
+For more documentation, read the source code in
+:file:`django/contrib/markup/templatetags/markup.py`.
+
+.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29
+.. _Markdown: http://en.wikipedia.org/wiki/Markdown
+.. _reST (reStructured Text): http://en.wikipedia.org/wiki/ReStructuredText
+.. _PyTextile: http://loopcore.com/python-textile/
+.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown
+.. _doc-utils: http://docutils.sf.net/
+
+reStructured Text
+-----------------
+
+When using the ``restructuredtext`` markup filter you can define a
+:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to
+override the default writer settings. See the `restructuredtext writer
+settings`_ for details on what these settings are.
+
+.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer
diff --git a/parts/django/docs/ref/contrib/messages.txt b/parts/django/docs/ref/contrib/messages.txt
new file mode 100644
index 0000000..3081f27
--- /dev/null
+++ b/parts/django/docs/ref/contrib/messages.txt
@@ -0,0 +1,411 @@
+======================
+The messages framework
+======================
+
+.. module:: django.contrib.messages
+   :synopsis: Provides cookie- and session-based temporary message storage.
+
+Django provides full support for cookie- and session-based messaging, for
+both anonymous and authenticated clients. The messages framework allows you
+to temporarily store messages in one request and retrieve them for display
+in a subsequent request (usually the next one). Every message is tagged
+with a specific ``level`` that determines its priority (e.g., ``info``,
+``warning``, or ``error``).
+
+.. versionadded:: 1.2
+   The messages framework was added.
+
+Enabling messages
+=================
+
+Messages are implemented through a :doc:`middleware </ref/middleware>`
+class and corresponding :doc:`context processor </ref/templates/api>`.
+
+To enable message functionality, do the following:
+
+    * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure
+      it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
+
+      If you are using a :ref:`storage backend <message-storage-backends>` that
+      relies on :doc:`sessions </topics/http/sessions>` (the default),
+      ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be
+      enabled and appear before ``MessageMiddleware`` in your
+      :setting:`MIDDLEWARE_CLASSES`.
+
+    * Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure
+      it contains ``'django.contrib.messages.context_processors.messages'``.
+
+    * Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS`
+      setting
+
+The default ``settings.py`` created by ``django-admin.py startproject`` has
+``MessageMiddleware`` activated and the ``django.contrib.messages`` app
+installed.  Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS`
+contains ``'django.contrib.messages.context_processors.messages'``.
+
+If you don't want to use messages, you can remove the
+``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages``
+context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and
+``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`.
+
+Configuring the message engine
+==============================
+
+.. _message-storage-backends:
+
+Storage backends
+----------------
+
+The messages framework can use different backends to store temporary messages.
+To change which backend is being used, add a `MESSAGE_STORAGE`_ to your
+settings, referencing the module and class of the storage class. For
+example::
+
+    MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
+
+The value should be the full path of the desired storage class.
+
+Four storage classes are included:
+
+``'django.contrib.messages.storage.session.SessionStorage'``
+    This class stores all messages inside of the request's session. It
+    requires Django's ``contrib.sessions`` application.
+
+``'django.contrib.messages.storage.cookie.CookieStorage'``
+    This class stores the message data in a cookie (signed with a secret hash
+    to prevent manipulation) to persist notifications across requests. Old
+    messages are dropped if the cookie data size would exceed 4096 bytes.
+
+``'django.contrib.messages.storage.fallback.FallbackStorage'``
+    This class first uses CookieStorage for all messages, falling back to using
+    SessionStorage for the messages that could not fit in a single cookie.
+
+    Since it is uses SessionStorage, it also requires Django's
+    ``contrib.session`` application.
+
+``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
+    This is the default temporary storage class.
+
+    This class extends FallbackStorage and adds compatibility methods to
+    to retrieve any messages stored in the user Message model by code that
+    has not yet been updated to use the new API. This storage is temporary
+    (because it makes use of code that is pending deprecation) and will be
+    removed in Django 1.4. At that time, the default storage will become
+    ``django.contrib.messages.storage.fallback.FallbackStorage``. For more
+    information, see `LegacyFallbackStorage`_ below.
+
+To write your own storage class, subclass the ``BaseStorage`` class in
+``django.contrib.messages.storage.base`` and implement the ``_get`` and
+``_store`` methods.
+
+LegacyFallbackStorage
+^^^^^^^^^^^^^^^^^^^^^
+
+The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition
+from the deprecated ``user.message_set`` API and will be removed in Django 1.4
+according to Django's standard deprecation policy.  For more information, see
+the full :doc:`release process documentation </internals/release-process>`.
+
+In addition to the functionality in the ``FallbackStorage``, it adds a custom,
+read-only storage class that retrieves messages from the user ``Message``
+model. Any messages that were stored in the ``Message`` model (e.g., by code
+that has not yet been updated to use the messages framework) will be retrieved
+first, followed by those stored in a cookie and in the session, if any.  Since
+messages stored in the ``Message`` model do not have a concept of levels, they
+will be assigned the ``INFO`` level by default.
+
+Message levels
+--------------
+
+The messages framework is based on a configurable level architecture similar
+to that of the Python logging module.  Message levels allow you to group
+messages by type so they can be filtered or displayed differently in views and
+templates.
+
+The built-in levels (which can be imported from ``django.contrib.messages``
+directly) are:
+
+=========== ========
+Constant    Purpose
+=========== ========
+``DEBUG``   Development-related messages that will be ignored (or removed) in a production deployment
+``INFO``    Informational messages for the user
+``SUCCESS`` An action was successful, e.g. "Your profile was updated successfully"
+``WARNING`` A failure did not occur but may be imminent
+``ERROR``   An action was **not** successful or some other failure occurred
+=========== ========
+
+The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level
+(or it can be `changed per request`_). Attempts to add messages of a level less
+than this will be ignored.
+
+.. _`changed per request`: `Changing the minimum recorded level per-request`_
+
+Message tags
+------------
+
+Message tags are a string representation of the message level plus any
+extra tags that were added directly in the view (see
+`Adding extra message tags`_ below for more details).  Tags are stored in a
+string and are separated by spaces.  Typically, message tags
+are used as CSS classes to customize message style based on message type. By
+default, each level has a single tag that's a lowercase version of its own
+constant:
+
+==============  ===========
+Level Constant  Tag
+==============  ===========
+``DEBUG``       ``debug``
+``INFO``        ``info``
+``SUCCESS``     ``success``
+``WARNING``     ``warning``
+``ERROR``       ``error``
+==============  ===========
+
+To change the default tags for a message level (either built-in or custom),
+set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels
+you wish to change. As this extends the default tags, you only need to provide
+tags for the levels you wish to override::
+
+    from django.contrib.messages import constants as messages
+    MESSAGE_TAGS = {
+        messages.INFO: '',
+        50: 'critical',
+    }
+
+Using messages in views and templates
+=====================================
+
+Adding a message
+----------------
+
+To add a message, call::
+
+    from django.contrib import messages
+    messages.add_message(request, messages.INFO, 'Hello world.')
+
+Some shortcut methods provide a standard way to add messages with commonly
+used tags (which are usually represented as HTML classes for the message)::
+
+    messages.debug(request, '%s SQL statements were executed.' % count)
+    messages.info(request, 'Three credits remain in your account.')
+    messages.success(request, 'Profile details updated.')
+    messages.warning(request, 'Your account expires in three days.')
+    messages.error(request, 'Document deleted.')
+
+Displaying messages
+-------------------
+
+In your template, use something like::
+
+    {% if messages %}
+    <ul class="messages">
+        {% for message in messages %}
+        <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
+        {% endfor %}
+    </ul>
+    {% endif %}
+
+If you're using the context processor, your template should be rendered with a
+``RequestContext``. Otherwise, ensure ``messages`` is available to
+the template context.
+
+Creating custom message levels
+------------------------------
+
+Messages levels are nothing more than integers, so you can define your own
+level constants and use them to create more customized user feedback, e.g.::
+
+    CRITICAL = 50
+
+    def my_view(request):
+        messages.add_message(request, CRITICAL, 'A serious error occurred.')
+
+When creating custom message levels you should be careful to avoid overloading
+existing levels.  The values for the built-in levels are:
+
+.. _message-level-constants:
+
+==============  =====
+Level Constant  Value
+==============  =====
+``DEBUG``       10
+``INFO``        20
+``SUCCESS``     25
+``WARNING``     30
+``ERROR``       40
+==============  =====
+
+If you need to identify the custom levels in your HTML or CSS, you need to
+provide a mapping via the `MESSAGE_TAGS`_ setting.
+
+.. note::
+   If you are creating a reusable application, it is recommended to use
+   only the built-in `message levels`_ and not rely on any custom levels.
+
+Changing the minimum recorded level per-request
+-----------------------------------------------
+
+The minimum recorded level can be set per request via the ``set_level``
+method::
+
+    from django.contrib import messages
+
+    # Change the messages level to ensure the debug message is added.
+    messages.set_level(request, messages.DEBUG)
+    messages.debug(request, 'Test message...')
+
+    # In another request, record only messages with a level of WARNING and higher
+    messages.set_level(request, messages.WARNING)
+    messages.success(request, 'Your profile was updated.') # ignored
+    messages.warning(request, 'Your account is about to expire.') # recorded
+
+    # Set the messages level back to default.
+    messages.set_level(request, None)
+
+Similarly, the current effective level can be retrieved with ``get_level``::
+
+    from django.contrib import messages
+    current_level = messages.get_level(request)
+
+For more information on how the minimum recorded level functions, see
+`Message levels`_ above.
+
+Adding extra message tags
+-------------------------
+
+For more direct control over message tags, you can optionally provide a string
+containing extra tags to any of the add methods::
+
+    messages.add_message(request, messages.INFO, 'Over 9000!',
+                         extra_tags='dragonball')
+    messages.error(request, 'Email box full', extra_tags='email')
+
+Extra tags are added before the default tag for that level and are space
+separated.
+
+Failing silently when the message framework is disabled
+-------------------------------------------------------
+
+If you're writing a reusable app (or other piece of code) and want to include
+messaging functionality, but don't want to require your users to enable it
+if they don't want to, you may pass an additional keyword argument
+``fail_silently=True`` to any of the ``add_message`` family of methods. For
+example::
+
+    messages.add_message(request, messages.SUCCESS, 'Profile details updated.',
+                         fail_silently=True)
+    messages.info(request, 'Hello world.', fail_silently=True)
+
+Internally, Django uses this functionality in the create, update, and delete
+:doc:`generic views </topics/http/generic-views>` so that they work even if the
+message framework is disabled.
+
+.. note::
+   Setting ``fail_silently=True`` only hides the ``MessageFailure`` that would
+   otherwise occur when the messages framework disabled and one attempts to
+   use one of the ``add_message`` family of methods.  It does not hide failures
+   that may occur for other reasons.
+
+Expiration of messages
+======================
+
+The messages are marked to be cleared when the storage instance is iterated
+(and cleared when the response is processed).
+
+To avoid the messages being cleared, you can set the messages storage to
+``False`` after iterating::
+
+    storage = messages.get_messages(request)
+    for message in storage:
+        do_something_with(message)
+    storage.used = False
+
+Behavior of parallel requests
+=============================
+
+Due to the way cookies (and hence sessions) work, **the behavior of any
+backends that make use of cookies or sessions is undefined when the same
+client makes multiple requests that set or get messages in parallel**.  For
+example, if a client initiates a request that creates a message in one window
+(or tab) and then another that fetches any uniterated messages in another
+window, before the first window redirects, the message may appear in the
+second window instead of the first window where it may be expected.
+
+In short, when multiple simultaneous requests from the same client are
+involved, messages are not guaranteed to be delivered to the same window that
+created them nor, in some cases, at all.  Note that this is typically not a
+problem in most applications and will become a non-issue in HTML5, where each
+window/tab will have its own browsing context.
+
+Settings
+========
+
+A few :doc:`Django settings </ref/settings>` give you control over message
+behavior:
+
+MESSAGE_LEVEL
+-------------
+
+Default: ``messages.INFO``
+
+This sets the minimum message that will be saved in the message storage.  See
+`Message levels`_ above for more details.
+
+.. admonition:: Important
+
+   If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of
+   the built-in constants, you must import the constants module directly to
+   avoid the potential for circular imports, e.g.::
+
+       from django.contrib.messages import constants as message_constants
+       MESSAGE_LEVEL = message_constants.DEBUG
+
+   If desired, you may specify the numeric values for the constants directly
+   according to the values in the above :ref:`constants table
+   <message-level-constants>`.
+
+MESSAGE_STORAGE
+---------------
+
+Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
+
+Controls where Django stores message data. Valid values are:
+
+    * ``'django.contrib.messages.storage.fallback.FallbackStorage'``
+    * ``'django.contrib.messages.storage.session.SessionStorage'``
+    * ``'django.contrib.messages.storage.cookie.CookieStorage'``
+    * ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
+
+See `Storage backends`_ for more details.
+
+MESSAGE_TAGS
+------------
+
+Default::
+
+        {messages.DEBUG: 'debug',
+        messages.INFO: 'info',
+        messages.SUCCESS: 'success',
+        messages.WARNING: 'warning',
+        messages.ERROR: 'error',}
+
+This sets the mapping of message level to message tag, which is typically
+rendered as a CSS class in HTML. If you specify a value, it will extend
+the default. This means you only have to specify those values which you need
+to override. See `Displaying messages`_ above for more details.
+
+.. admonition:: Important
+
+   If you override ``MESSAGE_TAGS`` in your settings file and rely on any of
+   the built-in constants, you must import the ``constants`` module directly to
+   avoid the potential for circular imports, e.g.::
+
+       from django.contrib.messages import constants as message_constants
+       MESSAGE_TAGS = {message_constants.INFO: ''}
+
+   If desired, you may specify the numeric values for the constants directly
+   according to the values in the above :ref:`constants table
+   <message-level-constants>`.
+
+.. _Django settings: ../settings/
diff --git a/parts/django/docs/ref/contrib/redirects.txt b/parts/django/docs/ref/contrib/redirects.txt
new file mode 100644
index 0000000..f1a58cb
--- /dev/null
+++ b/parts/django/docs/ref/contrib/redirects.txt
@@ -0,0 +1,70 @@
+=================
+The redirects app
+=================
+
+.. module:: django.contrib.redirects
+   :synopsis: A framework for managing redirects.
+
+Django comes with an optional redirects application. It lets you store simple
+redirects in a database and handles the redirecting for you.
+
+Installation
+============
+
+To install the redirects app, follow these steps:
+
+    1. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS`
+       setting.
+    2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
+       to your :setting:`MIDDLEWARE_CLASSES` setting.
+    3. Run the command :djadmin:`manage.py syncdb <syncdb>`.
+
+How it works
+============
+
+``manage.py syncdb`` creates a ``django_redirect`` table in your database. This
+is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields.
+
+The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django
+application raises a 404 error, this middleware checks the redirects database
+for the requested URL as a last resort. Specifically, it checks for a redirect
+with the given ``old_path`` with a site ID that corresponds to the
+:setting:`SITE_ID` setting.
+
+    * If it finds a match, and ``new_path`` is not empty, it redirects to
+      ``new_path``.
+    * If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone")
+      HTTP header and empty (content-less) response.
+    * If it doesn't find a match, the request continues to be processed as
+      usual.
+
+The middleware only gets activated for 404s -- not for 500s or responses of any
+other status code.
+
+Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
+can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a
+last resort.
+
+For more on middleware, read the :doc:`middleware docs
+</topics/http/middleware>`.
+
+How to add, change and delete redirects
+=======================================
+
+Via the admin interface
+-----------------------
+
+If you've activated the automatic Django admin interface, you should see a
+"Redirects" section on the admin index page. Edit redirects as you edit any
+other object in the system.
+
+Via the Python API
+------------------
+
+.. class:: models.Redirect
+
+    Redirects are represented by a standard :doc:`Django model </topics/db/models>`,
+    which lives in `django/contrib/redirects/models.py`_. You can access redirect
+    objects via the :doc:`Django database API </topics/db/queries>`.
+
+.. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py
diff --git a/parts/django/docs/ref/contrib/sitemaps.txt b/parts/django/docs/ref/contrib/sitemaps.txt
new file mode 100644
index 0000000..eb29c6c
--- /dev/null
+++ b/parts/django/docs/ref/contrib/sitemaps.txt
@@ -0,0 +1,351 @@
+=====================
+The sitemap framework
+=====================
+
+.. module:: django.contrib.sitemaps
+   :synopsis: A framework for generating Google sitemap XML files.
+
+Django comes with a high-level sitemap-generating framework that makes
+creating sitemap_ XML files easy.
+
+.. _sitemap: http://www.sitemaps.org/
+
+Overview
+========
+
+A sitemap is an XML file on your Web site that tells search-engine indexers how
+frequently your pages change and how "important" certain pages are in relation
+to other pages on your site. This information helps search engines index your
+site.
+
+The Django sitemap framework automates the creation of this XML file by letting
+you express this information in Python code.
+
+It works much like Django's :doc:`syndication framework
+</ref/contrib/syndication>`. To create a sitemap, just write a
+:class:`~django.contrib.sitemaps.Sitemap` class and point to it in your
+:doc:`URLconf </topics/http/urls>`.
+
+Installation
+============
+
+To install the sitemap app, follow these steps:
+
+    1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS`
+       setting.
+
+    2. Make sure ``'django.template.loaders.app_directories.Loader'``
+       is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default,
+       so you'll only need to change this if you've changed that setting.
+
+    3. Make sure you've installed the
+       :mod:`sites framework <django.contrib.sites>`.
+
+(Note: The sitemap application doesn't install any database tables. The only
+reason it needs to go into :setting:`INSTALLED_APPS` is so that the
+:func:`~django.template.loaders.app_directories.Loader` template
+loader can find the default templates.)
+
+Initialization
+==============
+
+To activate sitemap generation on your Django site, add this line to your
+:doc:`URLconf </topics/http/urls>`::
+
+   (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
+
+This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`.
+
+The name of the sitemap file is not important, but the location is. Search
+engines will only index links in your sitemap for the current URL level and
+below. For instance, if :file:`sitemap.xml` lives in your root directory, it may
+reference any URL in your site. However, if your sitemap lives at
+:file:`/content/sitemap.xml`, it may only reference URLs that begin with
+:file:`/content/`.
+
+The sitemap view takes an extra, required argument: ``{'sitemaps': sitemaps}``.
+``sitemaps`` should be a dictionary that maps a short section label (e.g.,
+``blog`` or ``news``) to its :class:`~django.contrib.sitemaps.Sitemap` class
+(e.g., ``BlogSitemap`` or ``NewsSitemap``). It may also map to an *instance* of
+a :class:`~django.contrib.sitemaps.Sitemap` class (e.g.,
+``BlogSitemap(some_var)``).
+
+Sitemap classes
+===============
+
+A :class:`~django.contrib.sitemaps.Sitemap` class is a simple Python
+class that represents a "section" of entries in your sitemap. For example,
+one :class:`~django.contrib.sitemaps.Sitemap` class could represent
+all the entries of your Weblog, while another could represent all of the
+events in your events calendar.
+
+In the simplest case, all these sections get lumped together into one
+:file:`sitemap.xml`, but it's also possible to use the framework to generate a
+sitemap index that references individual sitemap files, one per section. (See
+`Creating a sitemap index`_ below.)
+
+:class:`~django.contrib.sitemaps.Sitemap` classes must subclass
+``django.contrib.sitemaps.Sitemap``. They can live anywhere in your codebase.
+
+A simple example
+================
+
+Let's assume you have a blog system, with an ``Entry`` model, and you want your
+sitemap to include all the links to your individual blog entries. Here's how
+your sitemap class might look::
+
+    from django.contrib.sitemaps import Sitemap
+    from blog.models import Entry
+
+    class BlogSitemap(Sitemap):
+        changefreq = "never"
+        priority = 0.5
+
+        def items(self):
+            return Entry.objects.filter(is_draft=False)
+
+        def lastmod(self, obj):
+            return obj.pub_date
+
+Note:
+
+    * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class
+      attributes corresponding to ``<changefreq>`` and ``<priority>`` elements,
+      respectively. They can be made callable as functions, as
+      :attr:`~Sitemap.lastmod` was in the example.
+    * :attr:`~Sitemap.items()` is simply a method that returns a list of
+      objects. The objects returned will get passed to any callable methods
+      corresponding to a sitemap property (:attr:`~Sitemap.location`,
+      :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and
+      :attr:`~Sitemap.priority`).
+    * :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object.
+    * There is no :attr:`~Sitemap.location` method in this example, but you
+      can provide it in order to specify the URL for your object. By default,
+      :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object
+      and returns the result.
+
+Sitemap class reference
+=======================
+
+.. class:: Sitemap
+
+    A ``Sitemap`` class can define the following methods/attributes:
+
+    .. attribute:: Sitemap.items
+
+        **Required.** A method that returns a list of objects. The framework
+        doesn't care what *type* of objects they are; all that matters is that
+        these objects get passed to the :attr:`~Sitemap.location()`,
+        :attr:`~Sitemap.lastmod()`, :attr:`~Sitemap.changefreq()` and
+        :attr:`~Sitemap.priority()` methods.
+
+    .. attribute:: Sitemap.location
+
+        **Optional.** Either a method or attribute.
+
+        If it's a method, it should return the absolute path for a given object
+        as returned by :attr:`~Sitemap.items()`.
+
+        If it's an attribute, its value should be a string representing an
+        absolute path to use for *every* object returned by
+        :attr:`~Sitemap.items()`.
+
+        In both cases, "absolute path" means a URL that doesn't include the
+        protocol or domain. Examples:
+
+            * Good: :file:`'/foo/bar/'`
+            * Bad: :file:`'example.com/foo/bar/'`
+            * Bad: :file:`'http://example.com/foo/bar/'`
+
+        If :attr:`~Sitemap.location` isn't provided, the framework will call
+        the ``get_absolute_url()`` method on each object as returned by
+        :attr:`~Sitemap.items()`.
+
+    .. attribute:: Sitemap.lastmod
+
+        **Optional.** Either a method or attribute.
+
+        If it's a method, it should take one argument -- an object as returned by
+        :attr:`~Sitemap.items()` -- and return that object's last-modified date/time, as a Python
+        ``datetime.datetime`` object.
+
+        If it's an attribute, its value should be a Python ``datetime.datetime`` object
+        representing the last-modified date/time for *every* object returned by
+        :attr:`~Sitemap.items()`.
+
+    .. attribute:: Sitemap.changefreq
+
+        **Optional.** Either a method or attribute.
+
+        If it's a method, it should take one argument -- an object as returned by
+        :attr:`~Sitemap.items()` -- and return that object's change frequency, as a Python string.
+
+        If it's an attribute, its value should be a string representing the change
+        frequency of *every* object returned by :attr:`~Sitemap.items()`.
+
+        Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are:
+
+            * ``'always'``
+            * ``'hourly'``
+            * ``'daily'``
+            * ``'weekly'``
+            * ``'monthly'``
+            * ``'yearly'``
+            * ``'never'``
+
+    .. method:: Sitemap.priority
+
+        **Optional.** Either a method or attribute.
+
+        If it's a method, it should take one argument -- an object as returned by
+        :attr:`~Sitemap.items()` -- and return that object's priority, as either a string or float.
+
+        If it's an attribute, its value should be either a string or float representing
+        the priority of *every* object returned by :attr:`~Sitemap.items()`.
+
+        Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The default priority of a
+        page is ``0.5``. See the `sitemaps.org documentation`_ for more.
+
+        .. _sitemaps.org documentation: http://www.sitemaps.org/protocol.html#prioritydef
+
+Shortcuts
+=========
+
+The sitemap framework provides a couple convenience classes for common cases:
+
+.. class:: FlatPageSitemap
+
+    The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all
+    publicly visible :mod:`flatpages <django.contrib.flatpages>`
+    defined for the current :setting:`SITE_ID` (see the
+    :mod:`sites documentation <django.contrib.sites>`) and
+    creates an entry in the sitemap. These entries include only the
+    :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`,
+    :attr:`~Sitemap.changefreq` or :attr:`~Sitemap.priority`.
+
+.. class:: GenericSitemap
+
+    The :class:`django.contrib.sitemaps.GenericSitemap` class works with any
+    :doc:`generic views </ref/generic-views>` you already have.
+    To use it, create an instance, passing in the same :data:`info_dict` you pass to
+    the generic views. The only requirement is that the dictionary have a
+    :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a
+    date field for objects retrieved from the :data:`queryset`. This will be used for
+    the :attr:`~Sitemap.lastmod` attribute in the generated sitemap. You may
+    also pass :attr:`~Sitemap.priority` and :attr:`~Sitemap.changefreq`
+    keyword arguments to the :class:`~django.contrib.sitemaps.GenericSitemap`
+    constructor to specify these attributes for all URLs.
+
+Example
+-------
+
+Here's an example of a :doc:`URLconf </topics/http/urls>` using both::
+
+    from django.conf.urls.defaults import *
+    from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap
+    from blog.models import Entry
+
+    info_dict = {
+        'queryset': Entry.objects.all(),
+        'date_field': 'pub_date',
+    }
+
+    sitemaps = {
+        'flatpages': FlatPageSitemap,
+        'blog': GenericSitemap(info_dict, priority=0.6),
+    }
+
+    urlpatterns = patterns('',
+        # some generic view using info_dict
+        # ...
+
+        # the sitemap
+        (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
+    )
+
+.. _URLconf: ../url_dispatch/
+
+Creating a sitemap index
+========================
+
+The sitemap framework also has the ability to create a sitemap index that
+references individual sitemap files, one per each section defined in your
+:data:`sitemaps` dictionary. The only differences in usage are:
+
+    * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index`
+      and :func:`django.contrib.sitemaps.views.sitemap`.
+    * The :func:`django.contrib.sitemaps.views.sitemap` view should take a
+      :data:`section` keyword argument.
+
+Here's what the relevant URLconf lines would look like for the example above::
+
+   (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.index', {'sitemaps': sitemaps}),
+   (r'^sitemap-(?P<section>.+)\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}),
+
+This will automatically generate a :file:`sitemap.xml` file that references both
+:file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The
+:class:`~django.contrib.sitemaps.Sitemap` classes and the :data:`sitemaps` dict
+don't change at all.
+
+You should create an index file if one of your sitemaps has more than 50,000
+URLs. In this case, Django will automatically paginate the sitemap, and the
+index will reflect that.
+
+Pinging Google
+==============
+
+You may want to "ping" Google when your sitemap changes, to let it know to
+reindex your site. The sitemaps framework provides a function to do just
+that: :func:`django.contrib.sitemaps.ping_google()`.
+
+.. function:: ping_google
+
+    :func:`ping_google` takes an optional argument, :data:`sitemap_url`,
+    which should be the absolute path to your site's sitemap (e.g.,
+    :file:`'/sitemap.xml'`). If this argument isn't provided,
+    :func:`ping_google` will attempt to figure out your
+    sitemap by performing a reverse looking in your URLconf.
+
+    :func:`ping_google` raises the exception
+    :exc:`django.contrib.sitemaps.SitemapNotFound` if it cannot determine your
+    sitemap URL.
+
+.. admonition:: Register with Google first!
+
+    The :func:`ping_google` command only works if you have registered your
+    site with `Google Webmaster Tools`_.
+
+.. _`Google Webmaster Tools`: http://www.google.com/webmasters/tools/
+
+One useful way to call :func:`ping_google` is from a model's ``save()``
+method::
+
+   from django.contrib.sitemaps import ping_google
+
+    class Entry(models.Model):
+        # ...
+        def save(self, force_insert=False, force_update=False):
+            super(Entry, self).save(force_insert, force_update)
+            try:
+                ping_google()
+            except Exception:
+                # Bare 'except' because we could get a variety
+                # of HTTP-related exceptions.
+                pass
+
+A more efficient solution, however, would be to call :func:`ping_google` from a
+cron script, or some other scheduled task. The function makes an HTTP request
+to Google's servers, so you may not want to introduce that network overhead
+each time you call ``save()``.
+
+Pinging Google via `manage.py`
+------------------------------
+
+.. django-admin:: ping_google
+
+.. versionadded:: 1.0
+
+Once the sitemaps application is added to your project, you may also
+ping Google using the ``ping_google`` management command::
+
+    python manage.py ping_google [/sitemap.xml]
diff --git a/parts/django/docs/ref/contrib/sites.txt b/parts/django/docs/ref/contrib/sites.txt
new file mode 100644
index 0000000..6d795d0
--- /dev/null
+++ b/parts/django/docs/ref/contrib/sites.txt
@@ -0,0 +1,415 @@
+=====================
+The "sites" framework
+=====================
+
+.. module:: django.contrib.sites
+   :synopsis: Lets you operate multiple Web sites from the same database and
+              Django project
+
+Django comes with an optional "sites" framework. It's a hook for associating
+objects and functionality to particular Web sites, and it's a holding place for
+the domain names and "verbose" names of your Django-powered sites.
+
+Use it if your single Django installation powers more than one site and you
+need to differentiate between those sites in some way.
+
+The whole sites framework is based on a simple model:
+
+.. class:: django.contrib.sites.models.Site
+
+This model has :attr:`~django.contrib.sites.models.Site.domain` and
+:attr:`~django.contrib.sites.models.Site.name` fields. The :setting:`SITE_ID`
+setting specifies the database ID of the
+:class:`~django.contrib.sites.models.Site` object associated with that
+particular settings file.
+
+How you use this is up to you, but Django uses it in a couple of ways
+automatically via simple conventions.
+
+Example usage
+=============
+
+Why would you use sites? It's best explained through examples.
+
+Associating content with multiple sites
+---------------------------------------
+
+The Django-powered sites LJWorld.com_ and Lawrence.com_ are operated by the
+same news organization -- the Lawrence Journal-World newspaper in Lawrence,
+Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on local
+entertainment. But sometimes editors want to publish an article on *both*
+sites.
+
+The brain-dead way of solving the problem would be to require site producers to
+publish the same story twice: once for LJWorld.com and again for Lawrence.com.
+But that's inefficient for site producers, and it's redundant to store
+multiple copies of the same story in the database.
+
+The better solution is simple: Both sites use the same article database, and an
+article is associated with one or more sites. In Django model terminology,
+that's represented by a :class:`~django.db.models.ManyToManyField` in the
+``Article`` model::
+
+    from django.db import models
+    from django.contrib.sites.models import Site
+
+    class Article(models.Model):
+        headline = models.CharField(max_length=200)
+        # ...
+        sites = models.ManyToManyField(Site)
+
+This accomplishes several things quite nicely:
+
+    * It lets the site producers edit all content -- on both sites -- in a
+      single interface (the Django admin).
+
+    * It means the same story doesn't have to be published twice in the
+      database; it only has a single record in the database.
+
+    * It lets the site developers use the same Django view code for both sites.
+      The view code that displays a given story just checks to make sure the
+      requested story is on the current site. It looks something like this::
+
+          from django.conf import settings
+
+          def article_detail(request, article_id):
+              try:
+                  a = Article.objects.get(id=article_id, sites__id__exact=settings.SITE_ID)
+              except Article.DoesNotExist:
+                  raise Http404
+              # ...
+
+.. _ljworld.com: http://www.ljworld.com/
+.. _lawrence.com: http://www.lawrence.com/
+
+Associating content with a single site
+--------------------------------------
+
+Similarly, you can associate a model to the :class:`~django.contrib.sites.models.Site`
+model in a many-to-one relationship, using
+:class:`~django.db.models.fields.related.ForeignKey`.
+
+For example, if an article is only allowed on a single site, you'd use a model
+like this::
+
+    from django.db import models
+    from django.contrib.sites.models import Site
+
+    class Article(models.Model):
+        headline = models.CharField(max_length=200)
+        # ...
+        site = models.ForeignKey(Site)
+
+This has the same benefits as described in the last section.
+
+Hooking into the current site from views
+----------------------------------------
+
+You can use the sites framework in your Django views to do
+particular things based on the site in which the view is being called.
+For example::
+
+    from django.conf import settings
+
+    def my_view(request):
+        if settings.SITE_ID == 3:
+            # Do something.
+        else:
+            # Do something else.
+
+Of course, it's ugly to hard-code the site IDs like that. This sort of
+hard-coding is best for hackish fixes that you need done quickly. A slightly
+cleaner way of accomplishing the same thing is to check the current site's
+domain::
+
+    from django.conf import settings
+    from django.contrib.sites.models import Site
+
+    def my_view(request):
+        current_site = Site.objects.get(id=settings.SITE_ID)
+        if current_site.domain == 'foo.com':
+            # Do something
+        else:
+            # Do something else.
+
+The idiom of retrieving the :class:`~django.contrib.sites.models.Site` object
+for the value of :setting:`settings.SITE_ID <SITE_ID>` is quite common, so
+the :class:`~django.contrib.sites.models.Site` model's manager has a
+``get_current()`` method. This example is equivalent to the previous one::
+
+    from django.contrib.sites.models import Site
+
+    def my_view(request):
+        current_site = Site.objects.get_current()
+        if current_site.domain == 'foo.com':
+            # Do something
+        else:
+            # Do something else.
+
+.. versionchanged:: 1.3
+
+For code which relies on getting the current domain but cannot be certain
+that the sites framework will be installed for any given project, there is a
+utility function :func:`~django.contrib.sites.models.get_current_site` that
+takes a request object as an argument and returns either a Site instance (if
+the sites framework is installed) or a RequestSite instance (if it is not).
+This allows loose coupling with the sites framework and provides a usable
+fallback for cases where it is not installed.
+
+Getting the current domain for display
+--------------------------------------
+
+LJWorld.com and Lawrence.com both have e-mail alert functionality, which lets
+readers sign up to get notifications when news happens. It's pretty basic: A
+reader signs up on a Web form, and he immediately gets an e-mail saying,
+"Thanks for your subscription."
+
+It'd be inefficient and redundant to implement this signup-processing code
+twice, so the sites use the same code behind the scenes. But the "thank you for
+signing up" notice needs to be different for each site. By using
+:class:`~django.contrib.sites.models.Site`
+objects, we can abstract the "thank you" notice to use the values of the
+current site's :attr:`~django.contrib.sites.models.Site.name` and
+:attr:`~django.contrib.sites.models.Site.domain`.
+
+Here's an example of what the form-handling view looks like::
+
+    from django.contrib.sites.models import Site
+    from django.core.mail import send_mail
+
+    def register_for_newsletter(request):
+        # Check form values, etc., and subscribe the user.
+        # ...
+
+        current_site = Site.objects.get_current()
+        send_mail('Thanks for subscribing to %s alerts' % current_site.name,
+            'Thanks for your subscription. We appreciate it.\n\n-The %s team.' % current_site.name,
+            'editor@%s' % current_site.domain,
+            [user.email])
+
+        # ...
+
+On Lawrence.com, this e-mail has the subject line "Thanks for subscribing to
+lawrence.com alerts." On LJWorld.com, the e-mail has the subject "Thanks for
+subscribing to LJWorld.com alerts." Same goes for the e-mail's message body.
+
+Note that an even more flexible (but more heavyweight) way of doing this would
+be to use Django's template system. Assuming Lawrence.com and LJWorld.com have
+different template directories (:setting:`TEMPLATE_DIRS`), you could simply farm out
+to the template system like so::
+
+    from django.core.mail import send_mail
+    from django.template import loader, Context
+
+    def register_for_newsletter(request):
+        # Check form values, etc., and subscribe the user.
+        # ...
+
+        subject = loader.get_template('alerts/subject.txt').render(Context({}))
+        message = loader.get_template('alerts/message.txt').render(Context({}))
+        send_mail(subject, message, 'editor@ljworld.com', [user.email])
+
+        # ...
+
+In this case, you'd have to create :file:`subject.txt` and :file:`message.txt` template
+files for both the LJWorld.com and Lawrence.com template directories. That
+gives you more flexibility, but it's also more complex.
+
+It's a good idea to exploit the :class:`~django.contrib.sites.models.Site`
+objects as much as possible, to remove unneeded complexity and redundancy.
+
+Getting the current domain for full URLs
+----------------------------------------
+
+Django's ``get_absolute_url()`` convention is nice for getting your objects'
+URL without the domain name, but in some cases you might want to display the
+full URL -- with ``http://`` and the domain and everything -- for an object.
+To do this, you can use the sites framework. A simple example::
+
+    >>> from django.contrib.sites.models import Site
+    >>> obj = MyModel.objects.get(id=3)
+    >>> obj.get_absolute_url()
+    '/mymodel/objects/3/'
+    >>> Site.objects.get_current().domain
+    'example.com'
+    >>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url())
+    'http://example.com/mymodel/objects/3/'
+
+Caching the current ``Site`` object
+===================================
+
+.. versionadded:: 1.0
+
+As the current site is stored in the database, each call to
+``Site.objects.get_current()`` could result in a database query. But Django is a
+little cleverer than that: on the first request, the current site is cached, and
+any subsequent call returns the cached data instead of hitting the database.
+
+If for any reason you want to force a database query, you can tell Django to
+clear the cache using ``Site.objects.clear_cache()``::
+
+    # First call; current site fetched from database.
+    current_site = Site.objects.get_current()
+    # ...
+
+    # Second call; current site fetched from cache.
+    current_site = Site.objects.get_current()
+    # ...
+
+    # Force a database query for the third call.
+    Site.objects.clear_cache()
+    current_site = Site.objects.get_current()
+
+The ``CurrentSiteManager``
+==========================
+
+.. class:: django.contrib.sites.managers.CurrentSiteManager
+
+If :class:`~django.contrib.sites.models.Site` plays a key role in your
+application, consider using the helpful
+:class:`~django.contrib.sites.managers.CurrentSiteManager` in your
+model(s). It's a model :doc:`manager </topics/db/managers>` that
+automatically filters its queries to include only objects associated
+with the current :class:`~django.contrib.sites.models.Site`.
+
+Use :class:`~django.contrib.sites.managers.CurrentSiteManager` by adding it to
+your model explicitly. For example::
+
+    from django.db import models
+    from django.contrib.sites.models import Site
+    from django.contrib.sites.managers import CurrentSiteManager
+
+    class Photo(models.Model):
+        photo = models.FileField(upload_to='/home/photos')
+        photographer_name = models.CharField(max_length=100)
+        pub_date = models.DateField()
+        site = models.ForeignKey(Site)
+        objects = models.Manager()
+        on_site = CurrentSiteManager()
+
+With this model, ``Photo.objects.all()`` will return all ``Photo`` objects in
+the database, but ``Photo.on_site.all()`` will return only the ``Photo`` objects
+associated with the current site, according to the :setting:`SITE_ID` setting.
+
+Put another way, these two statements are equivalent::
+
+    Photo.objects.filter(site=settings.SITE_ID)
+    Photo.on_site.all()
+
+How did :class:`~django.contrib.sites.managers.CurrentSiteManager`
+know which field of ``Photo`` was the
+:class:`~django.contrib.sites.models.Site`? By default,
+:class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a
+either a :class:`~django.db.models.fields.related.ForeignKey` called
+``site`` or a
+:class:`~django.db.models.fields.related.ManyToManyField` called
+``sites`` to filter on. If you use a field named something other than
+``site`` or ``sites`` to identify which
+:class:`~django.contrib.sites.models.Site` objects your object is
+related to, then you need to explicitly pass the custom field name as
+a parameter to
+:class:`~django.contrib.sites.managers.CurrentSiteManager` on your
+model. The following model, which has a field called ``publish_on``,
+demonstrates this::
+
+    from django.db import models
+    from django.contrib.sites.models import Site
+    from django.contrib.sites.managers import CurrentSiteManager
+
+    class Photo(models.Model):
+        photo = models.FileField(upload_to='/home/photos')
+        photographer_name = models.CharField(max_length=100)
+        pub_date = models.DateField()
+        publish_on = models.ForeignKey(Site)
+        objects = models.Manager()
+        on_site = CurrentSiteManager('publish_on')
+
+If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager`
+and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`.
+
+Finally, note that you'll probably want to keep a normal
+(non-site-specific) ``Manager`` on your model, even if you use
+:class:`~django.contrib.sites.managers.CurrentSiteManager`. As
+explained in the :doc:`manager documentation </topics/db/managers>`, if
+you define a manager manually, then Django won't create the automatic
+``objects = models.Manager()`` manager for you. Also note that certain
+parts of Django -- namely, the Django admin site and generic views --
+use whichever manager is defined *first* in the model, so if you want
+your admin site to have access to all objects (not just site-specific
+ones), put ``objects = models.Manager()`` in your model, before you
+define :class:`~django.contrib.sites.managers.CurrentSiteManager`.
+
+How Django uses the sites framework
+===================================
+
+Although it's not required that you use the sites framework, it's strongly
+encouraged, because Django takes advantage of it in a few places. Even if your
+Django installation is powering only a single site, you should take the two
+seconds to create the site object with your ``domain`` and ``name``, and point
+to its ID in your :setting:`SITE_ID` setting.
+
+Here's how Django uses the sites framework:
+
+* In the :mod:`redirects framework <django.contrib.redirects>`, each
+  redirect object is associated with a particular site. When Django searches
+  for a redirect, it takes into account the current :setting:`SITE_ID`.
+
+* In the comments framework, each comment is associated with a particular
+  site. When a comment is posted, its
+  :class:`~django.contrib.sites.models.Site` is set to the current
+  :setting:`SITE_ID`, and when comments are listed via the appropriate
+  template tag, only the comments for the current site are displayed.
+
+* In the :mod:`flatpages framework <django.contrib.flatpages>`, each
+  flatpage is associated with a particular site. When a flatpage is created,
+  you specify its :class:`~django.contrib.sites.models.Site`, and the
+  :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
+  checks the current :setting:`SITE_ID` in retrieving flatpages to display.
+
+* In the :mod:`syndication framework <django.contrib.syndication>`, the
+  templates for ``title`` and ``description`` automatically have access to a
+  variable ``{{ site }}``, which is the
+  :class:`~django.contrib.sites.models.Site` object representing the current
+  site. Also, the hook for providing item URLs will use the ``domain`` from
+  the current :class:`~django.contrib.sites.models.Site` object if you don't
+  specify a fully-qualified domain.
+
+* In the :mod:`authentication framework <django.contrib.auth>`, the
+  :func:`django.contrib.auth.views.login` view passes the current
+  :class:`~django.contrib.sites.models.Site` name to the template as
+  ``{{ site_name }}``.
+
+* The shortcut view (:func:`django.views.defaults.shortcut`) uses the domain
+  of the current :class:`~django.contrib.sites.models.Site` object when
+  calculating an object's URL.
+
+* In the admin framework, the "view on site" link uses the current
+  :class:`~django.contrib.sites.models.Site` to work out the domain for the
+  site that it will redirect to.
+
+
+``RequestSite`` objects
+=======================
+
+.. _requestsite-objects:
+
+.. versionadded:: 1.0
+
+Some :doc:`django.contrib </ref/contrib/index>` applications take advantage of
+the sites framework but are architected in a way that doesn't *require* the
+sites framework to be installed in your database. (Some people don't want to, or
+just aren't *able* to install the extra database table that the sites framework
+requires.) For those cases, the framework provides a
+:class:`~django.contrib.sites.models.RequestSite` class, which can be used as a
+fallback when the database-backed sites framework is not available.
+
+A :class:`~django.contrib.sites.models.RequestSite` object has a similar
+interface to a normal :class:`~django.contrib.sites.models.Site` object, except
+its :meth:`~django.contrib.sites.models.RequestSite.__init__()` method takes an
+:class:`~django.http.HttpRequest` object. It's able to deduce the
+:attr:`~django.contrib.sites.models.RequestSite.domain` and
+:attr:`~django.contrib.sites.models.RequestSite.name` by looking at the
+request's domain. It has :meth:`~django.contrib.sites.models.RequestSite.save()`
+and :meth:`~django.contrib.sites.models.RequestSite.delete()` methods to match
+the interface of :class:`~django.contrib.sites.models.Site`, but the methods
+raise :exc:`NotImplementedError`.
diff --git a/parts/django/docs/ref/contrib/syndication.txt b/parts/django/docs/ref/contrib/syndication.txt
new file mode 100644
index 0000000..04f14b5
--- /dev/null
+++ b/parts/django/docs/ref/contrib/syndication.txt
@@ -0,0 +1,949 @@
+==============================
+The syndication feed framework
+==============================
+
+.. module:: django.contrib.syndication
+   :synopsis: A framework for generating syndication feeds, in RSS and Atom,
+              quite easily.
+
+Django comes with a high-level syndication-feed-generating framework
+that makes creating RSS_ and Atom_ feeds easy.
+
+To create any syndication feed, all you have to do is write a short
+Python class. You can create as many feeds as you want.
+
+Django also comes with a lower-level feed-generating API. Use this if
+you want to generate feeds outside of a Web context, or in some other
+lower-level way.
+
+.. _RSS: http://www.whatisrss.com/
+.. _Atom: http://www.atomenabled.org/
+
+The high-level framework
+========================
+
+.. versionchanged:: 1.2
+   The high-level feeds framework was refactored in Django 1.2. The
+   pre-1.2 interface still exists, but it has been deprecated, and
+   will be removed in Django 1.4. If you need to maintain an old-style
+   Django feed, please consult the Django 1.1 documentation. For
+   details on updating to use the new high-level feed framework, see
+   the :ref:`Django 1.2 release notes <1.2-updating-feeds>`.
+
+Overview
+--------
+
+The high-level feed-generating framework is supplied by the
+:class:`~django.contrib.syndication.views.Feed` class. To create a
+feed, write a :class:`~django.contrib.syndication.views.Feed` class
+and point to an instance of it in your :doc:`URLconf
+</topics/http/urls>`.
+
+Feed classes
+------------
+
+A :class:`~django.contrib.syndication.views.Feed` class is a Python
+class that represents a syndication feed. A feed can be simple (e.g.,
+a "site news" feed, or a basic feed displaying the latest entries of a
+blog) or more complex (e.g., a feed displaying all the blog entries in
+a particular category, where the category is variable).
+
+Feed classes subclass :class:`django.contrib.syndication.views.Feed`.
+They can live anywhere in your codebase.
+
+Instances of :class:`~django.contrib.syndication.views.Feed` classes
+are views which can be used in your :doc:`URLconf </topics/http/urls>`.
+
+A simple example
+----------------
+
+This simple example, taken from `chicagocrime.org`_, describes a feed of the
+latest five news items::
+
+    from django.contrib.syndication.views import Feed
+    from chicagocrime.models import NewsItem
+
+    class LatestEntriesFeed(Feed):
+        title = "Chicagocrime.org site news"
+        link = "/sitenews/"
+        description = "Updates on changes and additions to chicagocrime.org."
+
+        def items(self):
+            return NewsItem.objects.order_by('-pub_date')[:5]
+
+        def item_title(self, item):
+            return item.title
+
+        def item_description(self, item):
+            return item.description
+
+To connect a URL to this feed, put an instance of the Feed object in
+your :doc:`URLconf </topics/http/urls>`. For example::
+
+    from django.conf.urls.defaults import *
+    from myproject.feeds import LatestEntriesFeed
+
+    urlpatterns = patterns('',
+        # ...
+        (r'^latest/feed/$', LatestEntriesFeed()),
+        # ...
+    )
+
+Note:
+
+* The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.
+
+* :attr:`title`, :attr:`link` and :attr:`description` correspond to the
+  standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,
+  respectively.
+
+* :meth:`items()` is, simply, a method that returns a list of objects that
+  should be included in the feed as ``<item>`` elements. Although this
+  example returns ``NewsItem`` objects using Django's
+  :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()`
+  doesn't have to return model instances. Although you get a few bits of
+  functionality "for free" by using Django models, :meth:`items()` can
+  return any type of object you want.
+
+* If you're creating an Atom feed, rather than an RSS feed, set the
+  :attr:`subtitle` attribute instead of the :attr:`description` attribute.
+  See `Publishing Atom and RSS feeds in tandem`_, later, for an example.
+
+One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
+``<link>`` and ``<description>``. We need to tell the framework what data to put
+into those elements.
+
+    * For the contents of ``<title>`` and ``<description>``, Django tries
+      calling the methods :meth:`item_title()` and :meth:`item_description()` on
+      the :class:`~django.contrib.syndication.views.Feed` class. They are passed
+      a single parameter, :attr:`item`, which is the object itself. These are
+      optional; by default, the unicode representation of the object is used for
+      both.
+
+      If you want to do any special formatting for either the title or
+      description, :doc:`Django templates </topics/templates>` can be used
+      instead. Their paths can be specified with the ``title_template`` and
+      ``description_template`` attributes on the
+      :class:`~django.contrib.syndication.views.Feed` class. The templates are
+      rendered for each item and are passed two template context variables:
+
+         * ``{{ obj }}`` -- The current object (one of whichever objects you
+           returned in :meth:`items()`).
+
+         * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object
+           representing the current site. This is useful for ``{{ site.domain
+           }}`` or ``{{ site.name }}``. If you do *not* have the Django sites
+           framework installed, this will be set to a
+           :class:`django.contrib.sites.models.RequestSite` object. See the
+           :ref:`RequestSite section of the sites framework documentation
+           <requestsite-objects>` for more.
+
+      See `a complex example`_ below that uses a description template.
+
+    * To specify the contents of ``<link>``, you have two options. For each item
+      in :meth:`items()`, Django first tries calling the
+      :meth:`item_link()` method on the
+      :class:`~django.contrib.syndication.views.Feed` class. In a similar way to
+      the title and description, it is passed it a single parameter,
+      :attr:`item`. If that method doesn't exist, Django tries executing a
+      ``get_absolute_url()`` method on that object. Both
+      :meth:`get_absolute_url()` and :meth:`item_link()` should return the
+      item's URL as a normal Python string. As with ``get_absolute_url()``, the
+      result of :meth:`item_link()` will be included directly in the URL, so you
+      are responsible for doing all necessary URL quoting and conversion to
+      ASCII inside the method itself.
+
+.. _chicagocrime.org: http://www.chicagocrime.org/
+
+A complex example
+-----------------
+
+The framework also supports more complex feeds, via arguments.
+
+For example, `chicagocrime.org`_ offers an RSS feed of recent crimes for every
+police beat in Chicago. It'd be silly to create a separate
+:class:`~django.contrib.syndication.views.Feed` class for each police beat; that
+would violate the :ref:`DRY principle <dry>` and would couple data to
+programming logic. Instead, the syndication framework lets you access the
+arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output
+items based on information in the feed's URL.
+
+On chicagocrime.org, the police-beat feeds are accessible via URLs like this:
+
+    * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613.
+    * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424.
+
+These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
+
+    (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()),
+
+Like a view, the arguments in the URL are passed to the :meth:`get_object()`
+method along with the request object.
+
+.. versionchanged:: 1.2
+   Prior to version 1.2, ``get_object()`` only accepted a ``bits`` argument.
+
+Here's the code for these beat-specific feeds::
+
+    from django.contrib.syndication.views import FeedDoesNotExist
+    from django.shortcuts import get_object_or_404
+
+    class BeatFeed(Feed):
+        description_template = 'feeds/beat_description.html'
+
+        def get_object(self, request, beat_id):
+            return get_object_or_404(Beat, pk=beat_id)
+
+        def title(self, obj):
+            return "Chicagocrime.org: Crimes for beat %s" % obj.beat
+
+        def link(self, obj):
+            return obj.get_absolute_url()
+
+        def description(self, obj):
+            return "Crimes recently reported in police beat %s" % obj.beat
+
+        def items(self, obj):
+            return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30]
+
+To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django
+uses the :meth:`title()`, :meth:`link()` and :meth:`description()` methods. In
+the previous example, they were simple string class attributes, but this example
+illustrates that they can be either strings *or* methods. For each of
+:attr:`title`, :attr:`link` and :attr:`description`, Django follows this
+algorithm:
+
+    * First, it tries to call a method, passing the ``obj`` argument, where
+      ``obj`` is the object returned by :meth:`get_object()`.
+
+    * Failing that, it tries to call a method with no arguments.
+
+    * Failing that, it uses the class attribute.
+
+Also note that :meth:`items()` also follows the same algorithm -- first, it
+tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items`
+class attribute (which should be a list).
+
+We are using a template for the item descriptions. It can be very simple:
+
+.. code-block:: html+django
+
+    {{ obj.description }}
+
+However, you are free to add formatting as desired.
+
+The ``ExampleFeed`` class below gives full documentation on methods and
+attributes of :class:`~django.contrib.syndication.views.Feed` classes.
+
+Specifying the type of feed
+---------------------------
+
+By default, feeds produced in this framework use RSS 2.0.
+
+To change that, add a ``feed_type`` attribute to your
+:class:`~django.contrib.syndication.views.Feed` class, like so::
+
+    from django.utils.feedgenerator import Atom1Feed
+
+    class MyFeed(Feed):
+        feed_type = Atom1Feed
+
+Note that you set ``feed_type`` to a class object, not an instance.
+
+Currently available feed types are:
+
+    * :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.)
+    * :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.)
+    * :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.)
+
+Enclosures
+----------
+
+To specify enclosures, such as those used in creating podcast feeds, use the
+:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and
+:attr:`item_enclosure_mime_type` hooks. See the ``ExampleFeed`` class below for
+usage examples.
+
+Language
+--------
+
+Feeds created by the syndication framework automatically include the
+appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This
+comes directly from your :setting:`LANGUAGE_CODE` setting.
+
+URLs
+----
+
+The :attr:`link` method/attribute can return either an absolute path (e.g.
+:file:`"/blog/"`) or a URL with the fully-qualified domain and protocol (e.g.
+``"http://www.example.com/blog/"``). If :attr:`link` doesn't return the domain,
+the syndication framework will insert the domain of the current site, according
+to your :setting:`SITE_ID setting <SITE_ID>`.
+
+Atom feeds require a ``<link rel="self">`` that defines the feed's current
+location. The syndication framework populates this automatically, using the
+domain of the current site according to the :setting:`SITE_ID` setting.
+
+Publishing Atom and RSS feeds in tandem
+---------------------------------------
+
+Some developers like to make available both Atom *and* RSS versions of their
+feeds. That's easy to do with Django: Just create a subclass of your
+:class:`~django.contrib.syndication.views.Feed`
+class and set the :attr:`feed_type` to something different. Then update your
+URLconf to add the extra versions.
+
+Here's a full example::
+
+    from django.contrib.syndication.views import Feed
+    from chicagocrime.models import NewsItem
+    from django.utils.feedgenerator import Atom1Feed
+
+    class RssSiteNewsFeed(Feed):
+        title = "Chicagocrime.org site news"
+        link = "/sitenews/"
+        description = "Updates on changes and additions to chicagocrime.org."
+
+        def items(self):
+            return NewsItem.objects.order_by('-pub_date')[:5]
+
+    class AtomSiteNewsFeed(RssSiteNewsFeed):
+        feed_type = Atom1Feed
+        subtitle = RssSiteNewsFeed.description
+
+.. Note::
+    In this example, the RSS feed uses a :attr:`description` while the Atom
+    feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for
+    a feed-level "description," but they *do* provide for a "subtitle."
+
+    If you provide a :attr:`description` in your
+    :class:`~django.contrib.syndication.views.Feed` class, Django will *not*
+    automatically put that into the :attr:`subtitle` element, because a
+    subtitle and description are not necessarily the same thing. Instead, you
+    should define a :attr:`subtitle` attribute.
+
+    In the above example, we simply set the Atom feed's :attr:`subtitle` to the
+    RSS feed's :attr:`description`, because it's quite short already.
+
+And the accompanying URLconf::
+
+    from django.conf.urls.defaults import *
+    from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed
+
+    urlpatterns = patterns('',
+        # ...
+        (r'^sitenews/rss/$', RssSiteNewsFeed()),
+        (r'^sitenews/atom/$', AtomSiteNewsFeed()),
+        # ...
+    )
+
+Feed class reference
+--------------------
+
+.. class:: django.contrib.syndication.views.Feed
+
+This example illustrates all possible attributes and methods for a
+:class:`~django.contrib.syndication.views.Feed` class::
+
+    from django.contrib.syndication.views import Feed
+    from django.utils import feedgenerator
+
+    class ExampleFeed(Feed):
+
+        # FEED TYPE -- Optional. This should be a class that subclasses
+        # django.utils.feedgenerator.SyndicationFeed. This designates
+        # which type of feed this should be: RSS 2.0, Atom 1.0, etc. If
+        # you don't specify feed_type, your feed will be RSS 2.0. This
+        # should be a class, not an instance of the class.
+
+        feed_type = feedgenerator.Rss201rev2Feed
+
+        # TEMPLATE NAMES -- Optional. These should be strings
+        # representing names of Django templates that the system should
+        # use in rendering the title and description of your feed items.
+        # Both are optional. If a template is not specified, the
+        # item_title() or item_description() methods are used instead.
+
+        title_template = None
+        description_template = None
+
+        # TITLE -- One of the following three is required. The framework
+        # looks for them in this order.
+
+        def title(self, obj):
+            """
+            Takes the object returned by get_object() and returns the
+            feed's title as a normal Python string.
+            """
+
+        def title(self):
+            """
+            Returns the feed's title as a normal Python string.
+            """
+
+        title = 'foo' # Hard-coded title.
+
+        # LINK -- One of the following three is required. The framework
+        # looks for them in this order.
+
+        def link(self, obj):
+            """
+            # Takes the object returned by get_object() and returns the feed's
+            # link as a normal Python string.
+            """
+
+        def link(self):
+            """
+            Returns the feed's link as a normal Python string.
+            """
+
+        link = '/foo/bar/' # Hard-coded link.
+
+        # GUID -- One of the following three is optional. The framework looks
+        # for them in this order. This property is only used for Atom feeds
+        # (where it is the feed-level ID element). If not provided, the feed
+        # link is used as the ID.
+
+        def feed_guid(self, obj):
+            """
+            Takes the object returned by get_object() and returns the globally
+            unique ID for the feed as a normal Python string.
+            """
+
+        def feed_guid(self):
+            """
+            Returns the feed's globally unique ID as a normal Python string.
+            """
+
+        feed_guid = '/foo/bar/1234' # Hard-coded guid.
+
+        # DESCRIPTION -- One of the following three is required. The framework
+        # looks for them in this order.
+
+        def description(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            description as a normal Python string.
+            """
+
+        def description(self):
+            """
+            Returns the feed's description as a normal Python string.
+            """
+
+        description = 'Foo bar baz.' # Hard-coded description.
+
+        # AUTHOR NAME --One of the following three is optional. The framework
+        # looks for them in this order.
+
+        def author_name(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            author's name as a normal Python string.
+            """
+
+        def author_name(self):
+            """
+            Returns the feed's author's name as a normal Python string.
+            """
+
+        author_name = 'Sally Smith' # Hard-coded author name.
+
+        # AUTHOR E-MAIL --One of the following three is optional. The framework
+        # looks for them in this order.
+
+        def author_email(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            author's e-mail as a normal Python string.
+            """
+
+        def author_email(self):
+            """
+            Returns the feed's author's e-mail as a normal Python string.
+            """
+
+        author_email = 'test@example.com' # Hard-coded author e-mail.
+
+        # AUTHOR LINK --One of the following three is optional. The framework
+        # looks for them in this order. In each case, the URL should include
+        # the "http://" and domain name.
+
+        def author_link(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            author's URL as a normal Python string.
+            """
+
+        def author_link(self):
+            """
+            Returns the feed's author's URL as a normal Python string.
+            """
+
+        author_link = 'http://www.example.com/' # Hard-coded author URL.
+
+        # CATEGORIES -- One of the following three is optional. The framework
+        # looks for them in this order. In each case, the method/attribute
+        # should return an iterable object that returns strings.
+
+        def categories(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            categories as iterable over strings.
+            """
+
+        def categories(self):
+            """
+            Returns the feed's categories as iterable over strings.
+            """
+
+        categories = ("python", "django") # Hard-coded list of categories.
+
+        # COPYRIGHT NOTICE -- One of the following three is optional. The
+        # framework looks for them in this order.
+
+        def feed_copyright(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            copyright notice as a normal Python string.
+            """
+
+        def feed_copyright(self):
+            """
+            Returns the feed's copyright notice as a normal Python string.
+            """
+
+        feed_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+
+        # TTL -- One of the following three is optional. The framework looks
+        # for them in this order. Ignored for Atom feeds.
+
+        def ttl(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            TTL (Time To Live) as a normal Python string.
+            """
+
+        def ttl(self):
+            """
+            Returns the feed's TTL as a normal Python string.
+            """
+
+        ttl = 600 # Hard-coded Time To Live.
+
+        # ITEMS -- One of the following three is required. The framework looks
+        # for them in this order.
+
+        def items(self, obj):
+            """
+            Takes the object returned by get_object() and returns a list of
+            items to publish in this feed.
+            """
+
+        def items(self):
+            """
+            Returns a list of items to publish in this feed.
+            """
+
+        items = ('Item 1', 'Item 2') # Hard-coded items.
+
+        # GET_OBJECT -- This is required for feeds that publish different data
+        # for different URL parameters. (See "A complex example" above.)
+
+        def get_object(self, request, *args, **kwargs):
+            """
+            Takes the current request and the arguments from the URL, and
+            returns an object represented by this feed. Raises
+            django.core.exceptions.ObjectDoesNotExist on error.
+            """
+
+        # ITEM TITLE AND DESCRIPTION -- If title_template or
+        # description_template are not defined, these are used instead. Both are
+        # optional, by default they will use the unicode representation of the
+        # item.
+
+        def item_title(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            title as a normal Python string.
+            """
+
+        def item_title(self):
+            """
+            Returns the title for every item in the feed.
+            """
+
+        item_title = 'Breaking News: Nothing Happening' # Hard-coded title.
+
+        def item_description(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            description as a normal Python string.
+            """
+
+        def item_description(self):
+            """
+            Returns the description for every item in the feed.
+            """
+
+        item_description = 'A description of the item.' # Hard-coded description.
+
+        # ITEM LINK -- One of these three is required. The framework looks for
+        # them in this order.
+
+        # First, the framework tries the two methods below, in
+        # order. Failing that, it falls back to the get_absolute_url()
+        # method on each item returned by items().
+
+        def item_link(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's URL.
+            """
+
+        def item_link(self):
+            """
+            Returns the URL for every item in the feed.
+            """
+
+        # ITEM_GUID -- The following method is optional. If not provided, the
+        # item's link is used by default.
+
+        def item_guid(self, obj):
+            """
+            Takes an item, as return by items(), and returns the item's ID.
+            """
+
+        # ITEM AUTHOR NAME -- One of the following three is optional. The
+        # framework looks for them in this order.
+
+        def item_author_name(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            author's name as a normal Python string.
+            """
+
+        def item_author_name(self):
+            """
+            Returns the author name for every item in the feed.
+            """
+
+        item_author_name = 'Sally Smith' # Hard-coded author name.
+
+        # ITEM AUTHOR E-MAIL --One of the following three is optional. The
+        # framework looks for them in this order.
+        #
+        # If you specify this, you must specify item_author_name.
+
+        def item_author_email(self, obj):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            author's e-mail as a normal Python string.
+            """
+
+        def item_author_email(self):
+            """
+            Returns the author e-mail for every item in the feed.
+            """
+
+        item_author_email = 'test@example.com' # Hard-coded author e-mail.
+
+        # ITEM AUTHOR LINK -- One of the following three is optional. The
+        # framework looks for them in this order. In each case, the URL should
+        # include the "http://" and domain name.
+        #
+        # If you specify this, you must specify item_author_name.
+
+        def item_author_link(self, obj):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            author's URL as a normal Python string.
+            """
+
+        def item_author_link(self):
+            """
+            Returns the author URL for every item in the feed.
+            """
+
+        item_author_link = 'http://www.example.com/' # Hard-coded author URL.
+
+        # ITEM ENCLOSURE URL -- One of these three is required if you're
+        # publishing enclosures. The framework looks for them in this order.
+
+        def item_enclosure_url(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            enclosure URL.
+            """
+
+        def item_enclosure_url(self):
+            """
+            Returns the enclosure URL for every item in the feed.
+            """
+
+        item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
+
+        # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
+        # publishing enclosures. The framework looks for them in this order.
+        # In each case, the returned value should be either an integer, or a
+        # string representation of the integer, in bytes.
+
+        def item_enclosure_length(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            enclosure length.
+            """
+
+        def item_enclosure_length(self):
+            """
+            Returns the enclosure length for every item in the feed.
+            """
+
+        item_enclosure_length = 32000 # Hard-coded enclosure length.
+
+        # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
+        # publishing enclosures. The framework looks for them in this order.
+
+        def item_enclosure_mime_type(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            enclosure MIME type.
+            """
+
+        def item_enclosure_mime_type(self):
+            """
+            Returns the enclosure MIME type for every item in the feed.
+            """
+
+        item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
+
+        # ITEM PUBDATE -- It's optional to use one of these three. This is a
+        # hook that specifies how to get the pubdate for a given item.
+        # In each case, the method/attribute should return a Python
+        # datetime.datetime object.
+
+        def item_pubdate(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            pubdate.
+            """
+
+        def item_pubdate(self):
+            """
+            Returns the pubdate for every item in the feed.
+            """
+
+        item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
+
+        # ITEM CATEGORIES -- It's optional to use one of these three. This is
+        # a hook that specifies how to get the list of categories for a given
+        # item. In each case, the method/attribute should return an iterable
+        # object that returns strings.
+
+        def item_categories(self, item):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            categories.
+            """
+
+        def item_categories(self):
+            """
+            Returns the categories for every item in the feed.
+            """
+
+        item_categories = ("python", "django") # Hard-coded categories.
+
+        # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
+        # following three is optional. The framework looks for them in this
+        # order.
+
+        def item_copyright(self, obj):
+            """
+            Takes an item, as returned by items(), and returns the item's
+            copyright notice as a normal Python string.
+            """
+
+        def item_copyright(self):
+            """
+            Returns the copyright notice for every item in the feed.
+            """
+
+        item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+
+
+The low-level framework
+=======================
+
+Behind the scenes, the high-level RSS framework uses a lower-level framework
+for generating feeds' XML. This framework lives in a single module:
+`django/utils/feedgenerator.py`_.
+
+You use this framework on your own, for lower-level feed generation. You can
+also create custom feed generator subclasses for use with the ``feed_type``
+``Feed`` option.
+
+``SyndicationFeed`` classes
+---------------------------
+
+The :mod:`~django.utils.feedgenerator` module contains a base class:
+
+.. class:: django.utils.feedgenerator.SyndicationFeed
+
+and several subclasses:
+
+.. class:: django.utils.feedgenerator.RssUserland091Feed
+.. class:: django.utils.feedgenerator.Rss201rev2Feed
+.. class:: django.utils.feedgenerator.Atom1Feed
+
+Each of these three classes knows how to render a certain type of feed as XML.
+They share this interface:
+
+.. method:: SyndicationFeed.__init__(**kwargs)
+
+    Initialize the feed with the given dictionary of metadata, which applies to
+    the entire feed. Required keyword arguments are:
+
+        * ``title``
+        * ``link``
+        * ``description``
+
+    There's also a bunch of other optional keywords:
+
+        * ``language``
+        * ``author_email``
+        * ``author_name``
+        * ``author_link``
+        * ``subtitle``
+        * ``categories``
+        * ``feed_url``
+        * ``feed_copyright``
+        * ``feed_guid``
+        * ``ttl``
+
+    Any extra keyword arguments you pass to ``__init__`` will be stored in
+    ``self.feed`` for use with `custom feed generators`_.
+
+    All parameters should be Unicode objects, except ``categories``, which
+    should be a sequence of Unicode objects.
+
+.. method:: SyndicationFeed.add_item(**kwargs)
+
+    Add an item to the feed with the given parameters.
+
+    Required keyword arguments are:
+
+        * ``title``
+        * ``link``
+        * ``description``
+
+    Optional keyword arguments are:
+
+        * ``author_email``
+        * ``author_name``
+        * ``author_link``
+        * ``pubdate``
+        * ``comments``
+        * ``unique_id``
+        * ``enclosure``
+        * ``categories``
+        * ``item_copyright``
+        * ``ttl``
+
+    Extra keyword arguments will be stored for `custom feed generators`_.
+
+    All parameters, if given, should be Unicode objects, except:
+
+        * ``pubdate`` should be a `Python datetime object`_.
+        * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
+        * ``categories`` should be a sequence of Unicode objects.
+
+.. method:: SyndicationFeed.write(outfile, encoding)
+
+    Outputs the feed in the given encoding to outfile, which is a file-like object.
+
+.. method:: SyndicationFeed.writeString(encoding)
+
+    Returns the feed as a string in the given encoding.
+
+For example, to create an Atom 1.0 feed and print it to standard output::
+
+    >>> from django.utils import feedgenerator
+    >>> from datetime import datetime
+    >>> f = feedgenerator.Atom1Feed(
+    ...     title=u"My Weblog",
+    ...     link=u"http://www.example.com/",
+    ...     description=u"In which I write about what I ate today.",
+    ...     language=u"en",
+    ...     author_name=u"Myself",
+    ...     feed_url=u"http://example.com/atom.xml")
+    >>> f.add_item(title=u"Hot dog today",
+    ...     link=u"http://www.example.com/entries/1/",
+    ...     pubdate=datetime.now(),
+    ...     description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>")
+    >>> print f.writeString('UTF-8')
+    <?xml version="1.0" encoding="UTF-8"?>
+    <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
+    ...
+    </feed>
+
+.. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
+.. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects
+
+Custom feed generators
+----------------------
+
+If you need to produce a custom feed format, you've got a couple of options.
+
+If the feed format is totally custom, you'll want to subclass
+``SyndicationFeed`` and completely replace the ``write()`` and
+``writeString()`` methods.
+
+However, if the feed format is a spin-off of RSS or Atom (i.e. GeoRSS_, Apple's
+`iTunes podcast format`_, etc.), you've got a better choice. These types of
+feeds typically add extra elements and/or attributes to the underlying format,
+and there are a set of methods that ``SyndicationFeed`` calls to get these extra
+attributes. Thus, you can subclass the appropriate feed generator class
+(``Atom1Feed`` or ``Rss201rev2Feed``) and extend these callbacks. They are:
+
+.. _georss: http://georss.org/
+.. _itunes podcast format: http://www.apple.com/itunes/podcasts/specs.html
+
+``SyndicationFeed.root_attributes(self, )``
+    Return a ``dict`` of attributes to add to the root feed element
+    (``feed``/``channel``).
+
+``SyndicationFeed.add_root_elements(self, handler)``
+    Callback to add elements inside the root feed element
+    (``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's
+    built-in SAX library; you'll call methods on it to add to the XML
+    document in process.
+
+``SyndicationFeed.item_attributes(self, item)``
+    Return a ``dict`` of attributes to add to each item (``item``/``entry``)
+    element. The argument, ``item``, is a dictionary of all the data passed to
+    ``SyndicationFeed.add_item()``.
+
+``SyndicationFeed.add_item_elements(self, handler, item)``
+    Callback to add elements to each item (``item``/``entry``) element.
+    ``handler`` and ``item`` are as above.
+
+.. warning::
+
+    If you override any of these methods, be sure to call the superclass methods
+    since they add the required elements for each feed format.
+
+For example, you might start implementing an iTunes RSS feed generator like so::
+
+    class iTunesFeed(Rss201rev2Feed):
+        def root_attributes(self):
+            attrs = super(iTunesFeed, self).root_attributes()
+            attrs['xmlns:itunes'] = 'http://www.itunes.com/dtds/podcast-1.0.dtd'
+            return attrs
+
+        def add_root_elements(self, handler):
+            super(iTunesFeed, self).add_root_elements(handler)
+            handler.addQuickElement('itunes:explicit', 'clean')
+
+Obviously there's a lot more work to be done for a complete custom feed class,
+but the above example should demonstrate the basic idea.
+
+.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator
diff --git a/parts/django/docs/ref/contrib/webdesign.txt b/parts/django/docs/ref/contrib/webdesign.txt
new file mode 100644
index 0000000..d355d03
--- /dev/null
+++ b/parts/django/docs/ref/contrib/webdesign.txt
@@ -0,0 +1,56 @@
+========================
+django.contrib.webdesign
+========================
+
+.. module:: django.contrib.webdesign
+   :synopsis: Helpers and utilities targeted primarily at Web *designers*
+              rather than Web *developers*.
+
+The ``django.contrib.webdesign`` package, part of the
+:doc:`"django.contrib" add-ons </ref/contrib/index>`, provides various Django
+helpers that are particularly useful to Web *designers* (as opposed to
+developers).
+
+At present, the package contains only a single template tag. If you have ideas
+for Web-designer-friendly functionality in Django, please
+:doc:`suggest them </internals/contributing>`.
+
+Template tags
+=============
+
+To use these template tags, add ``'django.contrib.webdesign'`` to your
+:setting:`INSTALLED_APPS` setting. Once you've done that, use
+``{% load webdesign %}`` in a template to give your template access to the tags.
+
+
+lorem
+=====
+
+Displays random "lorem ipsum" Latin text. This is useful for providing sample
+data in templates.
+
+Usage::
+
+    {% lorem [count] [method] [random] %}
+
+The ``{% lorem %}`` tag can be used with zero, one, two or three arguments.
+The arguments are:
+
+    ===========  =============================================================
+    Argument     Description
+    ===========  =============================================================
+    ``count``    A number (or variable) containing the number of paragraphs or
+                 words to generate (default is 1).
+    ``method``   Either ``w`` for words, ``p`` for HTML paragraphs or ``b``
+                 for plain-text paragraph blocks (default is ``b``).
+    ``random``   The word ``random``, which if given, does not use the common
+                 paragraph ("Lorem ipsum dolor sit amet...") when generating
+                 text.
+    ===========  =============================================================
+
+Examples:
+
+    * ``{% lorem %}`` will output the common "lorem ipsum" paragraph.
+    * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph
+      and two random paragraphs each wrapped in HTML ``<p>`` tags.
+    * ``{% lorem 2 w random %}`` will output two random Latin words.
diff --git a/parts/django/docs/ref/databases.txt b/parts/django/docs/ref/databases.txt
new file mode 100644
index 0000000..c49a3fc
--- /dev/null
+++ b/parts/django/docs/ref/databases.txt
@@ -0,0 +1,682 @@
+=========
+Databases
+=========
+
+Django attempts to support as many features as possible on all database
+backends. However, not all database backends are alike, and we've had to make
+design decisions on which features to support and which assumptions we can make
+safely.
+
+This file describes some of the features that might be relevant to Django
+usage. Of course, it is not intended as a replacement for server-specific
+documentation or reference manuals.
+
+.. _postgresql-notes:
+
+PostgreSQL notes
+================
+
+PostgreSQL 8.2 to 8.2.4
+-----------------------
+
+The implementation of the population statistics aggregates ``STDDEV_POP`` and
+``VAR_POP`` that shipped with PostgreSQL 8.2 to 8.2.4 are `known to be
+faulty`_. Users of these releases of PostgreSQL are advised to upgrade to
+`Release 8.2.5`_ or later. Django will raise a ``NotImplementedError`` if you
+attempt to use the ``StdDev(sample=False)`` or ``Variance(sample=False)``
+aggregate with a database backend that falls within the affected release range.
+
+.. _known to be faulty: http://archives.postgresql.org/pgsql-bugs/2007-07/msg00046.php
+.. _Release 8.2.5: http://developer.postgresql.org/pgdocs/postgres/release-8-2-5.html
+
+Transaction handling
+---------------------
+
+:doc:`By default </topics/db/transactions>`, Django starts a transaction when a
+database connection is first used and commits the result at the end of the
+request/response handling. The PostgreSQL backends normally operate the same
+as any other Django backend in this respect.
+
+Autocommit mode
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.1
+
+If your application is particularly read-heavy and doesn't make many
+database writes, the overhead of a constantly open transaction can
+sometimes be noticeable. For those situations, if you're using the
+``postgresql_psycopg2`` backend, you can configure Django to use
+*"autocommit"* behavior for the connection, meaning that each database
+operation will normally be in its own transaction, rather than having
+the transaction extend over multiple operations. In this case, you can
+still manually start a transaction if you're doing something that
+requires consistency across multiple database operations. The
+autocommit behavior is enabled by setting the ``autocommit`` key in
+the :setting:`OPTIONS` part of your database configuration in
+:setting:`DATABASES`::
+
+    'OPTIONS': {
+        'autocommit': True,
+    }
+
+In this configuration, Django still ensures that :ref:`delete()
+<topics-db-queries-delete>` and :ref:`update() <topics-db-queries-update>`
+queries run inside a single transaction, so that either all the affected
+objects are changed or none of them are.
+
+.. admonition:: This is database-level autocommit
+
+    This functionality is not the same as the
+    :ref:`topics-db-transactions-autocommit` decorator. That decorator
+    is a Django-level implementation that commits automatically after
+    data changing operations. The feature enabled using the
+    :setting:`OPTIONS` option provides autocommit behavior at the
+    database adapter level. It commits after *every* operation.
+
+If you are using this feature and performing an operation akin to delete or
+updating that requires multiple operations, you are strongly recommended to
+wrap you operations in manual transaction handling to ensure data consistency.
+You should also audit your existing code for any instances of this behavior
+before enabling this feature. It's faster, but it provides less automatic
+protection for multi-call operations.
+
+Indexes for ``varchar`` and ``text`` columns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. versionadded:: 1.1.2
+
+When specifying ``db_index=True`` on your model fields, Django typically
+outputs a single ``CREATE INDEX`` statement.  However, if the database type
+for the field is either ``varchar`` or ``text`` (e.g., used by ``CharField``,
+``FileField``, and ``TextField``), then Django will create
+an additional index that uses an appropriate `PostgreSQL operator class`_
+for the column.  The extra index is necessary to correctly perfrom
+lookups that use the ``LIKE`` operator in their SQL, as is done with the
+``contains`` and ``startswith`` lookup types.
+
+.. _PostgreSQL operator class: http://www.postgresql.org/docs/8.4/static/indexes-opclass.html
+
+.. _mysql-notes:
+
+MySQL notes
+===========
+
+Django expects the database to support transactions, referential integrity, and
+Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these features as
+available as far back as 3.23. While it may be possible to use 3.23 or 4.0,
+you'll probably have less trouble if you use 4.1 or 5.0.
+
+MySQL 4.1
+---------
+
+`MySQL 4.1`_ has greatly improved support for character sets. It is possible to
+set different default character sets on the database, table, and column.
+Previous versions have only a server-wide character set setting. It's also the
+first version where the character set can be changed on the fly. 4.1 also has
+support for views, but Django currently doesn't use views.
+
+MySQL 5.0
+---------
+
+`MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed
+data on all database schema. Django's ``inspectdb`` feature uses this
+``information_schema`` if it's available. 5.0 also has support for stored
+procedures, but Django currently doesn't use stored procedures.
+
+.. _MySQL: http://www.mysql.com/
+.. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html
+.. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html
+
+Storage engines
+---------------
+
+MySQL has several `storage engines`_ (previously called table types). You can
+change the default storage engine in the server configuration.
+
+The default engine is MyISAM_ [#]_. The main drawback of MyISAM is that it
+doesn't currently support transactions or foreign keys. On the plus side, it's
+currently the only engine that supports full-text indexing and searching.
+
+The InnoDB_ engine is fully transactional and supports foreign key references.
+
+The BDB_ engine, like InnoDB, is also fully transactional and supports foreign
+key references. However, its use seems to be deprecated.
+
+`Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon.
+For now, InnoDB is probably your best choice.
+
+.. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html
+.. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html
+.. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html
+.. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html
+.. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html
+.. _SolidDB: http://forge.mysql.com/projects/project.php?id=139
+.. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html
+
+.. [#] Unless this was changed by the packager of your MySQL package. We've
+   had reports that the Windows Community Server installer sets up InnoDB as
+   the default storage engine, for example.
+
+MySQLdb
+-------
+
+`MySQLdb`_ is the Python interface to MySQL. Version 1.2.1p2 or later is
+required for full MySQL support in Django.
+
+.. note::
+    If you see ``ImportError: cannot import name ImmutableSet`` when trying to
+    use Django, your MySQLdb installation may contain an outdated ``sets.py``
+    file that conflicts with the built-in module of the same name from Python
+    2.4 and later. To fix this, verify that you have installed MySQLdb version
+    1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb
+    directory that was left by an earlier version.
+
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python
+
+Creating your database
+----------------------
+
+You can `create your database`_ using the command-line tools and this SQL::
+
+  CREATE DATABASE <dbname> CHARACTER SET utf8;
+
+This ensures all tables and columns will use UTF-8 by default.
+
+.. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html
+
+.. _mysql-collation:
+
+Collation settings
+~~~~~~~~~~~~~~~~~~
+
+The collation setting for a column controls the order in which data is sorted
+as well as what strings compare as equal. It can be set on a database-wide
+level and also per-table and per-column. This is `documented thoroughly`_ in
+the MySQL documentation. In all cases, you set the collation by directly
+manipulating the database tables; Django doesn't provide a way to set this on
+the model definition.
+
+.. _documented thoroughly: http://dev.mysql.com/doc/refman/5.0/en/charset.html
+
+By default, with a UTF-8 database, MySQL will use the
+``utf8_general_ci_swedish`` collation. This results in all string equality
+comparisons being done in a *case-insensitive* manner. That is, ``"Fred"`` and
+``"freD"`` are considered equal at the database level. If you have a unique
+constraint on a field, it would be illegal to try to insert both ``"aa"`` and
+``"AA"`` into the same column, since they compare as equal (and, hence,
+non-unique) with the default collation.
+
+In many cases, this default will not be a problem. However, if you really want
+case-sensitive comparisons on a particular column or table, you would change
+the column or table to use the ``utf8_bin`` collation. The main thing to be
+aware of in this case is that if you are using MySQLdb 1.2.2, the database
+backend in Django will then return bytestrings (instead of unicode strings) for
+any character fields it receive from the database. This is a strong variation
+from Django's normal practice of *always* returning unicode strings. It is up
+to you, the developer, to handle the fact that you will receive bytestrings if
+you configure your table(s) to use ``utf8_bin`` collation. Django itself should
+mostly work smoothly with such columns (except for the ``contrib.sessions``
+``Session`` and ``contrib.admin`` ``LogEntry`` tables described below), but
+your code must be prepared to call ``django.utils.encoding.smart_unicode()`` at
+times if it really wants to work with consistent data -- Django will not do
+this for you (the database backend layer and the model population layer are
+separated internally so the database layer doesn't know it needs to make this
+conversion in this one particular case).
+
+If you're using MySQLdb 1.2.1p2, Django's standard
+:class:`~django.db.models.CharField` class will return unicode strings even
+with ``utf8_bin`` collation. However, :class:`~django.db.models.TextField`
+fields will be returned as an ``array.array`` instance (from Python's standard
+``array`` module). There isn't a lot Django can do about that, since, again,
+the information needed to make the necessary conversions isn't available when
+the data is read in from the database. This problem was `fixed in MySQLdb
+1.2.2`_, so if you want to use :class:`~django.db.models.TextField` with
+``utf8_bin`` collation, upgrading to version 1.2.2 and then dealing with the
+bytestrings (which shouldn't be too difficult) as described above is the
+recommended solution.
+
+Should you decide to use ``utf8_bin`` collation for some of your tables with
+MySQLdb 1.2.1p2 or 1.2.2, you should still use ``utf8_collation_ci_swedish``
+(the default) collation for the :class:`django.contrib.sessions.models.Session`
+table (usually called ``django_session``) and the
+:class:`django.contrib.admin.models.LogEntry` table (usually called
+``django_admin_log``). Those are the two standard tables that use
+:class:`~django.db.model.TextField` internally.
+
+.. _fixed in MySQLdb 1.2.2: http://sourceforge.net/tracker/index.php?func=detail&aid=1495765&group_id=22307&atid=374932
+
+Connecting to the database
+--------------------------
+
+Refer to the :doc:`settings documentation </ref/settings>`.
+
+Connection settings are used in this order:
+
+    1. :setting:`OPTIONS`.
+    2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`,
+       :setting:`HOST`, :setting:`PORT`
+    3. MySQL option files.
+
+In other words, if you set the name of the database in ``OPTIONS``,
+this will take precedence over ``NAME``, which would override
+anything in a `MySQL option file`_.
+
+Here's a sample configuration which uses a MySQL option file::
+
+    # settings.py
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.mysql',
+            'OPTIONS': {
+                'read_default_file': '/path/to/my.cnf',
+            },
+        }
+    }
+
+
+    # my.cnf
+    [client]
+    database = NAME
+    user = USER
+    password = PASSWORD
+    default-character-set = utf8
+
+Several other MySQLdb connection options may be useful, such as ``ssl``,
+``use_unicode``, ``init_command``, and ``sql_mode``. Consult the
+`MySQLdb documentation`_ for more details.
+
+.. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html
+.. _MySQLdb documentation: http://mysql-python.sourceforge.net/
+
+Creating your tables
+--------------------
+
+When Django generates the schema, it doesn't specify a storage engine, so
+tables will be created with whatever default storage engine your database
+server is configured for. The easiest solution is to set your database server's
+default storage engine to the desired engine.
+
+If you're using a hosting service and can't change your server's default
+storage engine, you have a couple of options.
+
+    * After the tables are created, execute an ``ALTER TABLE`` statement to
+      convert a table to a new storage engine (such as InnoDB)::
+
+          ALTER TABLE <tablename> ENGINE=INNODB;
+
+      This can be tedious if you have a lot of tables.
+
+    * Another option is to use the ``init_command`` option for MySQLdb prior to
+      creating your tables::
+
+          'OPTIONS': {
+             'init_command': 'SET storage_engine=INNODB',
+          }
+
+      This sets the default storage engine upon connecting to the database.
+      After your tables have been created, you should remove this option.
+
+    * Another method for changing the storage engine is described in
+      AlterModelOnSyncDB_.
+
+.. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
+
+Notes on specific fields
+------------------------
+
+Boolean fields
+~~~~~~~~~~~~~~
+
+.. versionchanged:: 1.2
+
+In previous versions of Django when running under MySQL ``BooleanFields`` would
+return their data as ``ints``, instead of true ``bools``.  See the release
+notes for a complete description of the change.
+
+Character fields
+~~~~~~~~~~~~~~~~
+
+Any fields that are stored with ``VARCHAR`` column types have their
+``max_length`` restricted to 255 characters if you are using ``unique=True``
+for the field. This affects :class:`~django.db.models.CharField`,
+:class:`~django.db.models.SlugField` and
+:class:`~django.db.models.CommaSeparatedIntegerField`.
+
+Furthermore, if you are using a version of MySQL prior to 5.0.3, all of those
+column types have a maximum length restriction of 255 characters, regardless
+of whether ``unique=True`` is specified or not.
+
+.. _sqlite-notes:
+
+SQLite notes
+============
+
+SQLite_ provides an excellent development alternative for applications that
+are predominantly read-only or require a smaller installation footprint. As
+with all database servers, though, there are some differences that are
+specific to SQLite that you should be aware of.
+
+.. _SQLite: http://www.sqlite.org/
+
+.. _sqlite-string-matching:
+
+String matching for non-ASCII strings
+--------------------------------------
+
+SQLite doesn't support case-insensitive matching for non-ASCII strings. Some
+possible workarounds for this are `documented at sqlite.org`_, but they are
+not utilised by the default SQLite backend in Django. Therefore, if you are
+using the ``iexact`` lookup type in your queryset filters, be aware that it
+will not work as expected for non-ASCII strings.
+
+.. _documented at sqlite.org: http://www.sqlite.org/faq.html#q18
+
+SQLite 3.3.6 or newer strongly recommended
+------------------------------------------
+
+Versions of SQLite 3.3.5 and older contains the following bugs:
+
+ * A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when
+   you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug
+   can be identified by the error message ``OperationalError: ORDER BY terms
+   must not be non-integer constants``.
+
+ * A bug when handling `aggregation`_ together with DateFields and
+   DecimalFields.
+
+.. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768
+.. _aggregation: http://code.djangoproject.com/ticket/10031
+
+SQLite 3.3.6 was released in April 2006, so most current binary distributions
+for different platforms include newer version of SQLite usable from Python
+through either the ``pysqlite2`` or the ``sqlite3`` modules.
+
+However, some platform/Python version combinations include older versions of
+SQLite (e.g. the official binary distribution of Python 2.5 for Windows, 2.5.4
+as of this writing, includes SQLite 3.3.4). There are (as of Django 1.1) even
+some tests in the Django test suite that will fail when run under this setup.
+
+As described :ref:`below<using-newer-versions-of-pysqlite>`, this can be solved
+by downloading and installing a newer version of ``pysqlite2``
+(``pysqlite-2.x.x.win32-py2.5.exe`` in the described case) that includes and
+uses a newer version of SQLite. Python 2.6 for Windows ships with a version of
+SQLite that is not affected by these issues.
+
+Version 3.5.9
+-------------
+
+The Ubuntu "Intrepid Ibex" (8.10) SQLite 3.5.9-3 package contains a bug that
+causes problems with the evaluation of query expressions. If you are using
+Ubuntu "Intrepid Ibex", you will need to update the package to version
+3.5.9-3ubuntu1 or newer (recommended) or find an alternate source for SQLite
+packages, or install SQLite from source.
+
+At one time, Debian Lenny shipped with the same malfunctioning SQLite 3.5.9-3
+package. However the Debian project has subsequently issued updated versions
+of the SQLite package that correct these bugs. If you find you are getting
+unexpected results under Debian, ensure you have updated your SQLite package
+to 3.5.9-5 or later.
+
+The problem does not appear to exist with other versions of SQLite packaged
+with other operating systems.
+
+Version 3.6.2
+--------------
+
+SQLite version 3.6.2 (released August 30, 2008) introduced a bug into ``SELECT
+DISTINCT`` handling that is triggered by, amongst other things, Django's
+``DateQuerySet`` (returned by the ``dates()`` method on a queryset).
+
+You should avoid using this version of SQLite with Django. Either upgrade to
+3.6.3 (released September 22, 2008) or later, or downgrade to an earlier
+version of SQLite.
+
+.. _using-newer-versions-of-pysqlite:
+
+Using newer versions of the SQLite DB-API 2.0 driver
+----------------------------------------------------
+
+.. versionadded:: 1.1
+
+For versions of Python 2.5 or newer that include ``sqlite3`` in the standard
+library Django will now use a ``pysqlite2`` interface in preference to
+``sqlite3`` if it finds one is available.
+
+This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3
+itself to versions newer than the ones included with your particular Python
+binary distribution, if needed.
+
+"Database is locked" errors
+-----------------------------------------------
+
+SQLite is meant to be a lightweight database, and thus can't support a high
+level of concurrency. ``OperationalError: database is locked`` errors indicate
+that your application is experiencing more concurrency than ``sqlite`` can
+handle in default configuration. This error means that one thread or process has
+an exclusive lock on the database connection and another thread timed out
+waiting for the lock the be released.
+
+Python's SQLite wrapper has
+a default timeout value that determines how long the second thread is allowed to
+wait on the lock before it times out and raises the ``OperationalError: database
+is locked`` error.
+
+If you're getting this error, you can solve it by:
+
+    * Switching to another database backend. At a certain point SQLite becomes
+      too "lite" for real-world applications, and these sorts of concurrency
+      errors indicate you've reached that point.
+
+    * Rewriting your code to reduce concurrency and ensure that database
+      transactions are short-lived.
+
+    * Increase the default timeout value by setting the ``timeout`` database
+      option option::
+
+          'OPTIONS': {
+              # ...
+              'timeout': 20,
+              # ...
+          }
+
+      This will simply make SQLite wait a bit longer before throwing "database
+      is locked" errors; it won't really do anything to solve them.
+
+.. _oracle-notes:
+
+Oracle notes
+============
+
+Django supports `Oracle Database Server`_ versions 9i and
+higher. Oracle version 10g or later is required to use Django's
+``regex`` and ``iregex`` query operators. You will also need at least
+version 4.3.1 of the `cx_Oracle`_ Python driver.
+
+Note that due to a Unicode-corruption bug in ``cx_Oracle`` 5.0, that
+version of the driver should **not** be used with Django;
+``cx_Oracle`` 5.0.1 resolved this issue, so if you'd like to use a
+more recent ``cx_Oracle``, use version 5.0.1.
+
+``cx_Oracle`` 5.0.1 or greater can optionally be compiled with the
+``WITH_UNICODE`` environment variable.  This is recommended but not
+required.
+
+.. _`Oracle Database Server`: http://www.oracle.com/
+.. _`cx_Oracle`: http://cx-oracle.sourceforge.net/
+
+In order for the ``python manage.py syncdb`` command to work, your Oracle
+database user must have privileges to run the following commands:
+
+    * CREATE TABLE
+    * CREATE SEQUENCE
+    * CREATE PROCEDURE
+    * CREATE TRIGGER
+
+To run Django's test suite, the user needs these *additional* privileges:
+
+    * CREATE USER
+    * DROP USER
+    * CREATE TABLESPACE
+    * DROP TABLESPACE
+    * CONNECT WITH ADMIN OPTION
+    * RESOURCE WITH ADMIN OPTION
+
+Connecting to the database
+--------------------------
+
+Your Django settings.py file should look something like this for Oracle::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.oracle',
+            'NAME': 'xe',
+            'USER': 'a_user',
+            'PASSWORD': 'a_password',
+            'HOST': '',
+            'PORT': '',
+        }
+    }
+
+
+If you don't use a ``tnsnames.ora`` file or a similar naming method that
+recognizes the SID ("xe" in this example), then fill in both
+``HOST`` and ``PORT`` like so::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.oracle',
+            'NAME': 'xe',
+            'USER': 'a_user',
+            'PASSWORD': 'a_password',
+            'HOST': 'dbprod01ned.mycompany.com',
+            'PORT': '1540',
+        }
+    }
+
+You should supply both ``HOST`` and ``PORT``, or leave both
+as empty strings.
+
+Threaded option
+----------------
+
+If you plan to run Django in a multithreaded environment (e.g. Apache in Windows
+using the default MPM module), then you **must** set the ``threaded`` option of
+your Oracle database configuration to True::
+
+            'OPTIONS': {
+                'threaded': True,
+            },
+
+Failure to do this may result in crashes and other odd behavior.
+
+Tablespace options
+------------------
+
+A common paradigm for optimizing performance in Oracle-based systems is the
+use of `tablespaces`_ to organize disk layout. The Oracle backend supports
+this use case by adding ``db_tablespace`` options to the ``Meta`` and
+``Field`` classes.  (When you use a backend that lacks support for tablespaces,
+Django ignores these options.)
+
+.. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
+
+A tablespace can be specified for the table(s) generated by a model by
+supplying the ``db_tablespace`` option inside the model's ``class Meta``.
+Additionally, you can pass the ``db_tablespace`` option to a ``Field``
+constructor to specify an alternate tablespace for the ``Field``'s column
+index. If no index would be created for the column, the ``db_tablespace``
+option is ignored::
+
+    class TablespaceExample(models.Model):
+        name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes")
+        data = models.CharField(max_length=255, db_index=True)
+        edges = models.ManyToManyField(to="self", db_tablespace="indexes")
+
+        class Meta:
+            db_tablespace = "tables"
+
+In this example, the tables generated by the ``TablespaceExample`` model
+(i.e., the model table and the many-to-many table) would be stored in the
+``tables`` tablespace. The index for the name field and the indexes on the
+many-to-many table would be stored in the ``indexes`` tablespace. The ``data``
+field would also generate an index, but no tablespace for it is specified, so
+it would be stored in the model tablespace ``tables`` by default.
+
+.. versionadded:: 1.0
+
+Use the :setting:`DEFAULT_TABLESPACE` and :setting:`DEFAULT_INDEX_TABLESPACE`
+settings to specify default values for the db_tablespace options.
+These are useful for setting a tablespace for the built-in Django apps and
+other applications whose code you cannot control.
+
+Django does not create the tablespaces for you. Please refer to `Oracle's
+documentation`_ for details on creating and managing tablespaces.
+
+.. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403
+
+Naming issues
+-------------
+
+Oracle imposes a name length limit of 30 characters. To accommodate this, the
+backend truncates database identifiers to fit, replacing the final four
+characters of the truncated name with a repeatable MD5 hash value.
+
+When running syncdb, an ``ORA-06552`` error may be encountered if
+certain Oracle keywords are used as the name of a model field or the
+value of a ``db_column`` option.  Django quotes all identifiers used
+in queries to prevent most such problems, but this error can still
+occur when an Oracle datatype is used as a column name.  In
+particular, take care to avoid using the names ``date``,
+``timestamp``, ``number`` or ``float`` as a field name.
+
+NULL and empty strings
+----------------------
+
+Django generally prefers to use the empty string ('') rather than
+NULL, but Oracle treats both identically. To get around this, the
+Oracle backend coerces the ``null=True`` option on fields that have
+the empty string as a possible value. When fetching from the database,
+it is assumed that a NULL value in one of these fields really means
+the empty string, and the data is silently converted to reflect this
+assumption.
+
+``TextField`` limitations
+-------------------------
+
+The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes
+some limitations on the usage of such LOB columns in general:
+
+  * LOB columns may not be used as primary keys.
+
+  * LOB columns may not be used in indexes.
+
+  * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that
+    attempting to use the ``QuerySet.distinct`` method on a model that
+    includes ``TextField`` columns will result in an error when run against
+    Oracle. As a workaround, use the ``QuerySet.defer`` method in conjunction
+    with ``distinct()`` to prevent ``TextField`` columns from being included in
+    the ``SELECT DISTINCT`` list.
+
+.. _third-party-notes:
+
+Using a 3rd-party database backend
+==================================
+
+In addition to the officially supported databases, there are backends provided
+by 3rd parties that allow you to use other databases with Django:
+
+* `Sybase SQL Anywhere`_
+* `IBM DB2`_
+* `Microsoft SQL Server 2005`_
+* Firebird_
+* ODBC_
+
+The Django versions and ORM features supported by these unofficial backends
+vary considerably. Queries regarding the specific capabilities of these
+unofficial backends, along with any support queries, should be directed to
+the support channels provided by each 3rd party project.
+
+.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
+.. _IBM DB2: http://code.google.com/p/ibm-db/
+.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
+.. _Firebird: http://code.google.com/p/django-firebird/
+.. _ODBC: http://code.google.com/p/django-pyodbc/
diff --git a/parts/django/docs/ref/django-admin.txt b/parts/django/docs/ref/django-admin.txt
new file mode 100644
index 0000000..70faa3c
--- /dev/null
+++ b/parts/django/docs/ref/django-admin.txt
@@ -0,0 +1,1293 @@
+=============================
+django-admin.py and manage.py
+=============================
+
+``django-admin.py`` is Django's command-line utility for administrative tasks.
+This document outlines all it can do.
+
+In addition, ``manage.py`` is automatically created in each Django project.
+``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of
+two things for you before delegating to ``django-admin.py``:
+
+    * It puts your project's package on ``sys.path``.
+
+    * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
+      it points to your project's ``settings.py`` file.
+
+The ``django-admin.py`` script should be on your system path if you installed
+Django via its ``setup.py`` utility. If it's not on your path, you can find it
+in ``site-packages/django/bin`` within your Python installation. Consider
+symlinking it from some place on your path, such as ``/usr/local/bin``.
+
+For Windows users, who do not have symlinking functionality available, you can
+copy ``django-admin.py`` to a location on your existing path or edit the
+``PATH`` settings (under ``Settings - Control Panel - System - Advanced -
+Environment...``) to point to its installed location.
+
+Generally, when working on a single Django project, it's easier to use
+``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the
+``--settings`` command line option, if you need to switch between multiple
+Django settings files.
+
+The command-line examples throughout this document use ``django-admin.py`` to
+be consistent, but any example can use ``manage.py`` just as well.
+
+Usage
+=====
+
+.. code-block:: bash
+
+    django-admin.py <command> [options]
+    manage.py <command> [options]
+
+``command`` should be one of the commands listed in this document.
+``options``, which is optional, should be zero or more of the options available
+for the given command.
+
+Getting runtime help
+--------------------
+
+.. django-admin-option:: --help
+
+Run ``django-admin.py help`` to display a list of all available commands.
+Run ``django-admin.py help <command>`` to display a description of the
+given command and a list of its available options.
+
+App names
+---------
+
+Many commands take a list of "app names." An "app name" is the basename of
+the package containing your models. For example, if your ``INSTALLED_APPS``
+contains the string ``'mysite.blog'``, the app name is ``blog``.
+
+Determining the version
+-----------------------
+
+.. django-admin-option:: --version
+
+Run ``django-admin.py --version`` to display the current Django version.
+
+Examples of output::
+
+    0.95
+    0.96
+    0.97-pre-SVN-6069
+
+Displaying debug output
+-----------------------
+
+Use :djadminopt:`--verbosity` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console. For more details, see the
+documentation for the :djadminopt:`--verbosity` option.
+
+Available commands
+==================
+
+cleanup
+-------
+
+.. django-admin:: cleanup
+
+.. versionadded:: 1.0
+
+Can be run as a cronjob or directly to clean out old data from the database
+(only expired sessions at the moment).
+
+compilemessages
+---------------
+
+.. django-admin:: compilemessages
+
+.. versionchanged:: 1.0
+   Before 1.0 this was the "bin/compile-messages.py" command.
+
+Compiles .po files created with ``makemessages`` to .mo files for use with
+the builtin gettext support. See :doc:`/topics/i18n/index`.
+
+Use the :djadminopt:`--locale` option to specify the locale to process.
+If not provided, all locales are processed.
+
+Example usage::
+
+    django-admin.py compilemessages --locale=br_PT
+
+createcachetable
+----------------
+
+.. django-admin:: createcachetable
+
+Creates a cache table named ``tablename`` for use with the database cache
+backend. See :doc:`/topics/cache` for more information.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the cachetable will be installed.
+
+dbshell
+-------
+
+.. django-admin:: dbshell
+
+Runs the command-line client for the database engine specified in your
+``ENGINE`` setting, with the connection parameters specified in your
+``USER``, ``PASSWORD``, etc., settings.
+
+    * For PostgreSQL, this runs the ``psql`` command-line client.
+    * For MySQL, this runs the ``mysql`` command-line client.
+    * For SQLite, this runs the ``sqlite3`` command-line client.
+
+This command assumes the programs are on your ``PATH`` so that a simple call to
+the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
+the right place. There's no way to specify the location of the program
+manually.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which to open a shell.
+
+diffsettings
+------------
+
+.. django-admin:: diffsettings
+
+Displays differences between the current settings file and Django's default
+settings.
+
+Settings that don't appear in the defaults are followed by ``"###"``. For
+example, the default settings don't define ``ROOT_URLCONF``, so
+``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``.
+
+Note that Django's default settings live in ``django/conf/global_settings.py``,
+if you're ever curious to see the full list of defaults.
+
+dumpdata <appname appname appname.Model ...>
+--------------------------------------------
+
+.. django-admin:: dumpdata
+
+Outputs to standard output all data in the database associated with the named
+application(s).
+
+If no application name is provided, all installed applications will be dumped.
+
+The output of ``dumpdata`` can be used as input for ``loaddata``.
+
+Note that ``dumpdata`` uses the default manager on the model for selecting the
+records to dump. If you're using a :ref:`custom manager <custom-managers>` as
+the default manager and it filters some of the available records, not all of the
+objects will be dumped.
+
+.. django-admin-option:: --format <fmt>
+
+By default, ``dumpdata`` will format its output in JSON, but you can use the
+``--format`` option to specify another format. Currently supported formats
+are listed in :ref:`serialization-formats`.
+
+.. django-admin-option:: --indent <num>
+
+By default, ``dumpdata`` will output all data on a single line. This isn't
+easy for humans to read, so you can use the ``--indent`` option to
+pretty-print the output with a number of indentation spaces.
+
+.. versionadded:: 1.0
+
+The :djadminopt:`--exclude` option may be provided to prevent specific
+applications from being dumped.
+
+.. versionadded:: 1.1
+
+In addition to specifying application names, you can provide a list of
+individual models, in the form of ``appname.Model``. If you specify a model
+name to ``dumpdata``, the dumped output will be restricted to that model,
+rather than the entire application. You can also mix application names and
+model names.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the data will be loaded.
+
+.. django-admin-option:: --natural
+
+.. versionadded:: 1.2
+
+Use :ref:`natural keys <topics-serialization-natural-keys>` to represent
+any foreign key and many-to-many relationship with a model that provides
+a natural key definition. If you are dumping ``contrib.auth`` ``Permission``
+objects or ``contrib.contenttypes`` ``ContentType`` objects, you should
+probably be using this flag.
+
+flush
+-----
+
+.. django-admin:: flush
+
+Returns the database to the state it was in immediately after syncdb was
+executed. This means that all data will be removed from the database, any
+post-synchronization handlers will be re-executed, and the ``initial_data``
+fixture will be re-installed.
+
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option may be used to specify the database
+to flush.
+
+
+inspectdb
+---------
+
+.. django-admin:: inspectdb
+
+Introspects the database tables in the database pointed-to by the
+``NAME`` setting and outputs a Django model module (a ``models.py``
+file) to standard output.
+
+Use this if you have a legacy database with which you'd like to use Django.
+The script will inspect the database and create a model for each table within
+it.
+
+As you might expect, the created models will have an attribute for every field
+in the table. Note that ``inspectdb`` has a few special cases in its field-name
+output:
+
+    * If ``inspectdb`` cannot map a column's type to a model field type, it'll
+      use ``TextField`` and will insert the Python comment
+      ``'This field type is a guess.'`` next to the field in the generated
+      model.
+
+    * If the database column name is a Python reserved word (such as
+      ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append
+      ``'_field'`` to the attribute name. For example, if a table has a column
+      ``'for'``, the generated model will have a field ``'for_field'``, with
+      the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert
+      the Python comment
+      ``'Field renamed because it was a Python reserved word.'`` next to the
+      field.
+
+This feature is meant as a shortcut, not as definitive model generation. After
+you run it, you'll want to look over the generated models yourself to make
+customizations. In particular, you'll need to rearrange models' order, so that
+models that refer to other models are ordered properly.
+
+Primary keys are automatically introspected for PostgreSQL, MySQL and
+SQLite, in which case Django puts in the ``primary_key=True`` where
+needed.
+
+``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
+only works in PostgreSQL and with certain types of MySQL tables.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option may be used to specify the
+database to introspect.
+
+loaddata <fixture fixture ...>
+------------------------------
+
+.. django-admin:: loaddata
+
+Searches for and loads the contents of the named fixture into the database.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the data will be loaded.
+
+What's a "fixture"?
+~~~~~~~~~~~~~~~~~~~
+
+A *fixture* is a collection of files that contain the serialized contents of
+the database. Each fixture has a unique name, and the files that comprise the
+fixture can be distributed over multiple directories, in multiple applications.
+
+Django will search in three locations for fixtures:
+
+   1. In the ``fixtures`` directory of every installed application
+   2. In any directory named in the ``FIXTURE_DIRS`` setting
+   3. In the literal path named by the fixture
+
+Django will load any and all fixtures it finds in these locations that match
+the provided fixture names.
+
+If the named fixture has a file extension, only fixtures of that type
+will be loaded. For example::
+
+    django-admin.py loaddata mydata.json
+
+would only load JSON fixtures called ``mydata``. The fixture extension
+must correspond to the registered name of a
+:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
+
+If you omit the extensions, Django will search all available fixture types
+for a matching fixture. For example::
+
+    django-admin.py loaddata mydata
+
+would look for any fixture of any fixture type called ``mydata``. If a fixture
+directory contained ``mydata.json``, that fixture would be loaded
+as a JSON fixture.
+
+The fixtures that are named can include directory components. These
+directories will be included in the search path. For example::
+
+    django-admin.py loaddata foo/bar/mydata.json
+
+would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed
+application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
+``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``.
+
+When fixture files are processed, the data is saved to the database as is.
+Model defined ``save`` methods and ``pre_save`` signals are not called.
+
+Note that the order in which fixture files are processed is undefined. However,
+all fixture data is installed as a single transaction, so data in
+one fixture can reference data in another fixture. If the database backend
+supports row-level constraints, these constraints will be checked at the
+end of the transaction.
+
+The ``dumpdata`` command can be used to generate input for ``loaddata``.
+
+Compressed fixtures
+~~~~~~~~~~~~~~~~~~~
+
+Fixtures may be compressed in ``zip``, ``gz``, or ``bz2`` format. For example::
+
+    django-admin.py loaddata mydata.json
+
+would look for any of ``mydata.json``, ``mydata.json.zip``,
+``mydata.json.gz``, or ``mydata.json.bz2``.  The first file contained within a
+zip-compressed archive is used.
+
+Note that if two fixtures with the same name but different
+fixture type are discovered (for example, if ``mydata.json`` and
+``mydata.xml.gz`` were found in the same fixture directory), fixture
+installation will be aborted, and any data installed in the call to
+``loaddata`` will be removed from the database.
+
+.. admonition:: MySQL and Fixtures
+
+    Unfortunately, MySQL isn't capable of completely supporting all the
+    features of Django fixtures. If you use MyISAM tables, MySQL doesn't
+    support transactions or constraints, so you won't get a rollback if
+    multiple transaction files are found, or validation of fixture data.
+    If you use InnoDB tables, you won't be able to have any forward
+    references in your data files - MySQL doesn't provide a mechanism to
+    defer checking of row constraints until a transaction is committed.
+
+Database-specific fixtures
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are in a multi-database setup, you may have fixture data that
+you want to load onto one database, but not onto another. In this
+situation, you can add database identifier into . If your
+:setting:`DATABASES` setting has a 'master' database defined, you can
+define the fixture ``mydata.master.json`` or
+``mydata.master.json.gz``. This fixture will only be loaded if you
+have specified that you want to load data onto the ``master``
+database.
+
+makemessages
+------------
+
+.. django-admin:: makemessages
+
+.. versionchanged:: 1.0
+   Before 1.0 this was the ``bin/make-messages.py`` command.
+
+Runs over the entire source tree of the current directory and pulls out all
+strings marked for translation. It creates (or updates) a message file in the
+conf/locale (in the django tree) or locale (for project and application)
+directory. After making changes to the messages files you need to compile them
+with ``compilemessages`` for use with the builtin gettext support. See the
+:ref:`i18n documentation <how-to-create-language-files>` for details.
+
+.. django-admin-option:: --all
+
+Use the ``--all`` or ``-a`` option to update the message files for all
+available languages.
+
+Example usage::
+
+    django-admin.py makemessages --all
+
+.. django-admin-option:: --extension
+
+Use the ``--extension`` or ``-e`` option to specify a list of file extensions
+to examine (default: ".html").
+
+Example usage::
+
+    django-admin.py makemessages --locale=de --extension xhtml
+
+Separate multiple extensions with commas or use -e or --extension multiple times::
+
+    django-admin.py makemessages --locale=de --extension=html,txt --extension xml
+
+Use the :djadminopt:`--locale` option to specify the locale to process.
+
+Example usage::
+
+    django-admin.py makemessages --locale=br_PT
+
+.. django-admin-option:: --domain
+
+Use the ``--domain`` or ``-d`` option to change the domain of the messages files.
+Currently supported:
+
+    * ``django`` for all ``*.py`` and ``*.html`` files (default)
+    * ``djangojs`` for ``*.js`` files
+
+.. django-admin-option:: --symlinks
+
+.. versionadded:: 1.2
+
+Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when
+looking for new translation strings.
+
+Example usage::
+
+    django-admin.py makemessages --locale=de --symlinks
+
+.. django-admin-option:: --ignore
+
+Use the ``--ignore`` or ``-i`` option to ignore files or directories matching
+the given `glob-style pattern`_. Use multiple times to ignore more.
+
+These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``
+
+Example usage::
+
+    django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
+
+.. _`glob-style pattern`: http://docs.python.org/library/glob.html
+
+.. django-admin-option:: --no-default-ignore
+
+Use the ``--no-default-ignore`` option to disable the default values of
+:djadminopt:`--ignore`.
+
+reset <appname appname ...>
+---------------------------
+
+.. django-admin:: reset
+
+Executes the equivalent of ``sqlreset`` for the given app name(s).
+
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the alias
+of the database to reset.
+
+runfcgi [options]
+-----------------
+
+.. django-admin:: runfcgi
+
+Starts a set of FastCGI processes suitable for use with any Web server that
+supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation
+</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from
+`flup`_.
+
+.. _flup: http://www.saddi.com/software/flup/
+
+The options accepted by this command are passed to the FastCGI library and
+don't use the ``'--'`` prefix as is usual for other Django management commands.
+
+.. django-admin-option:: protocol
+
+``protocol=PROTOCOL``
+
+Protocol to use. *PROTOCOL* can be ``fcgi``, ``scgi``, ``ajp``, etc.
+(default is ``fcgi``)
+
+.. django-admin-option:: host
+
+``host=HOSTNAME``
+
+Hostname to listen on.
+
+.. django-admin-option:: port
+
+``port=PORTNUM``
+
+Port to listen on.
+
+.. django-admin-option:: socket
+
+``socket=FILE``
+
+UNIX socket to listen on.
+
+.. django-admin-option:: method
+
+``method=IMPL``
+
+Possible values: ``prefork`` or ``threaded`` (default ``prefork``)
+
+.. django-admin-option:: maxrequests
+
+``maxrequests=NUMBER``
+
+Number of requests a child handles before it is killed and a new child is
+forked (0 means no limit).
+
+.. django-admin-option:: maxspare
+
+``maxspare=NUMBER``
+
+Max number of spare processes / threads.
+
+.. django-admin-option:: minspare
+
+``minspare=NUMBER``
+
+Min number of spare processes / threads.
+
+.. django-admin-option:: maxchildren
+
+``maxchildren=NUMBER``
+
+Hard limit number of processes / threads.
+
+.. django-admin-option:: daemonize
+
+``daemonize=BOOL``
+
+Whether to detach from terminal.
+
+.. django-admin-option:: pidfile
+
+``pidfile=FILE``
+
+Write the spawned process-id to file *FILE*.
+
+.. django-admin-option:: workdir
+
+``workdir=DIRECTORY``
+
+Change to directory *DIRECTORY* when daemonizing.
+
+.. django-admin-option:: debug
+
+``debug=BOOL``
+
+Set to true to enable flup tracebacks.
+
+.. django-admin-option:: outlog
+
+``outlog=FILE``
+
+Write stdout to the *FILE* file.
+
+.. django-admin-option:: errlog
+
+``errlog=FILE``
+
+Write stderr to the *FILE* file.
+
+.. django-admin-option:: umask
+
+``umask=UMASK``
+
+Umask to use when daemonizing. The value is interpeted as an octal number
+(default value is ``022``).
+
+Example usage::
+
+    django-admin.py runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \
+        pidfile=/var/run/django-fcgi.pid
+
+Run a FastCGI server as a daemon and write the spawned PID in a file.
+
+runserver [port or ipaddr:port]
+-------------------------------
+
+.. django-admin:: runserver
+
+Starts a lightweight development Web server on the local machine. By default,
+the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an
+IP address and port number explicitly.
+
+If you run this script as a user with normal privileges (recommended), you
+might not have access to start a port on a low port number. Low port numbers
+are reserved for the superuser (root).
+
+DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through
+security audits or performance tests. (And that's how it's gonna stay. We're in
+the business of making Web frameworks, not Web servers, so improving this
+server to be able to handle a production environment is outside the scope of
+Django.)
+
+The development server automatically reloads Python code for each request, as
+needed. You don't need to restart the server for code changes to take effect.
+
+When you start the server, and each time you change Python code while the
+server is running, the server will validate all of your installed models. (See
+the ``validate`` command below.) If the validator finds errors, it will print
+them to standard output, but it won't stop the server.
+
+You can run as many servers as you want, as long as they're on separate ports.
+Just execute ``django-admin.py runserver`` more than once.
+
+Note that the default IP address, 127.0.0.1, is not accessible from other
+machines on your network. To make your development server viewable to other
+machines on the network, use its own IP address (e.g. ``192.168.2.1``) or
+``0.0.0.0``.
+
+.. django-admin-option:: --adminmedia
+
+Use the ``--adminmedia`` option to tell Django where to find the various CSS
+and JavaScript files for the Django admin interface. Normally, the development
+server serves these files out of the Django source tree magically, but you'd
+want to use this if you made any changes to those files for your own site.
+
+Example usage::
+
+    django-admin.py runserver --adminmedia=/tmp/new-admin-style/
+
+.. django-admin-option:: --noreload
+
+Use the ``--noreload`` option to disable the use of the auto-reloader. This
+means any Python code changes you make while the server is running will *not*
+take effect if the particular Python modules have already been loaded into
+memory.
+
+Example usage::
+
+    django-admin.py runserver --noreload
+
+Examples of using different ports and addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Port 8000 on IP address 127.0.0.1::
+
+	django-admin.py runserver
+
+Port 8000 on IP address 1.2.3.4::
+
+	django-admin.py runserver 1.2.3.4:8000
+
+Port 7000 on IP address 127.0.0.1::
+
+    django-admin.py runserver 7000
+
+Port 7000 on IP address 1.2.3.4::
+
+    django-admin.py runserver 1.2.3.4:7000
+
+Serving static files with the development server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the development server doesn't serve any static files for your site
+(such as CSS files, images, things under ``MEDIA_URL`` and so forth). If
+you want to configure Django to serve static media, read :doc:`/howto/static-files`.
+
+shell
+-----
+
+.. django-admin:: shell
+
+Starts the Python interactive interpreter.
+
+Django will use IPython_, if it's installed. If you have IPython installed and
+want to force use of the "plain" Python interpreter, use the ``--plain``
+option, like so::
+
+    django-admin.py shell --plain
+
+.. _IPython: http://ipython.scipy.org/
+
+sql <appname appname ...>
+-------------------------
+
+.. django-admin:: sql
+
+Prints the CREATE TABLE SQL statements for the given app name(s).
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlall <appname appname ...>
+----------------------------
+
+.. django-admin:: sqlall
+
+Prints the CREATE TABLE and initial-data SQL statements for the given app name(s).
+
+Refer to the description of ``sqlcustom`` for an explanation of how to
+specify initial data.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlclear <appname appname ...>
+------------------------------
+
+.. django-admin:: sqlclear
+
+Prints the DROP TABLE SQL statements for the given app name(s).
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlcustom <appname appname ...>
+-------------------------------
+
+.. django-admin:: sqlcustom
+
+Prints the custom SQL statements for the given app name(s).
+
+For each model in each specified app, this command looks for the file
+``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given app name and
+``<modelname>`` is the model's name in lowercase. For example, if you have an
+app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt
+to read a file ``news/sql/story.sql`` and append it to the output of this
+command.
+
+Each of the SQL files, if given, is expected to contain valid SQL. The SQL
+files are piped directly into the database after all of the models'
+table-creation statements have been executed. Use this SQL hook to make any
+table modifications, or insert any SQL functions into the database.
+
+Note that the order in which the SQL files are processed is undefined.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlflush
+--------
+
+.. django-admin:: sqlflush
+
+Prints the SQL statements that would be executed for the :djadmin:`flush`
+command.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlindexes <appname appname ...>
+--------------------------------
+
+.. django-admin:: sqlindexes
+
+Prints the CREATE INDEX SQL statements for the given app name(s).
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlreset <appname appname ...>
+------------------------------
+
+.. django-admin:: sqlreset
+
+Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+sqlsequencereset <appname appname ...>
+--------------------------------------
+
+.. django-admin:: sqlsequencereset
+
+Prints the SQL statements for resetting sequences for the given app name(s).
+
+Sequences are indexes used by some database engines to track the next available
+number for automatically incremented fields.
+
+Use this command to generate SQL which will fix cases where a sequence is out
+of sync with its automatically incremented field data.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
+startapp <appname>
+------------------
+
+.. django-admin:: startapp
+
+Creates a Django app directory structure for the given app name in the current
+directory.
+
+startproject <projectname>
+--------------------------
+
+.. django-admin:: startproject
+
+Creates a Django project directory structure for the given project name in the
+current directory.
+
+This command is disabled when the ``--settings`` option to
+``django-admin.py`` is used, or when the environment variable
+``DJANGO_SETTINGS_MODULE`` has been set. To re-enable it in these
+situations, either omit the ``--settings`` option or unset
+``DJANGO_SETTINGS_MODULE``.
+
+syncdb
+------
+
+.. django-admin:: syncdb
+
+Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
+have not already been created.
+
+Use this command when you've added new applications to your project and want to
+install them in the database. This includes any apps shipped with Django that
+might be in ``INSTALLED_APPS`` by default. When you start a new project, run
+this command to install the default apps.
+
+.. admonition:: Syncdb will not alter existing tables
+
+   ``syncdb`` will only create tables for models which have not yet been
+   installed. It will *never* issue ``ALTER TABLE`` statements to match
+   changes made to a model class after installation. Changes to model classes
+   and database schemas often involve some form of ambiguity and, in those
+   cases, Django would have to guess at the correct changes to make. There is
+   a risk that critical data would be lost in the process.
+
+   If you have made changes to a model and wish to alter the database tables
+   to match, use the ``sql`` command to display the new SQL structure and
+   compare that to your existing table schema to work out the changes.
+
+If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
+give you the option of creating a superuser immediately.
+
+``syncdb`` will also search for and install any fixture named ``initial_data``
+with an appropriate extension (e.g. ``json`` or ``xml``). See the
+documentation for ``loaddata`` for details on the specification of fixture
+data files.
+
+--noinput
+~~~~~~~~~
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database to
+synchronize.
+
+test <app or test identifier>
+-----------------------------
+
+.. django-admin:: test
+
+Runs tests for all installed models. See :doc:`/topics/testing` for more
+information.
+
+.. versionadded:: 1.2
+.. django-admin-option:: --failfast
+
+Use the :djadminopt:`--failfast` option to stop running tests and report the failure
+immediately after a test fails.
+
+testserver <fixture fixture ...>
+--------------------------------
+
+.. django-admin:: testserver
+
+.. versionadded:: 1.0
+
+Runs a Django development server (as in ``runserver``) using data from the
+given fixture(s).
+
+For example, this command::
+
+    django-admin.py testserver mydata.json
+
+...would perform the following steps:
+
+    1. Create a test database, as described in :doc:`/topics/testing`.
+    2. Populate the test database with fixture data from the given fixtures.
+       (For more on fixtures, see the documentation for ``loaddata`` above.)
+    3. Runs the Django development server (as in ``runserver``), pointed at
+       this newly created test database instead of your production database.
+
+This is useful in a number of ways:
+
+    * When you're writing :doc:`unit tests </topics/testing>` of how your views
+      act with certain fixture data, you can use ``testserver`` to interact with
+      the views in a Web browser, manually.
+
+    * Let's say you're developing your Django application and have a "pristine"
+      copy of a database that you'd like to interact with. You can dump your
+      database to a fixture (using the ``dumpdata`` command, explained above),
+      then use ``testserver`` to run your Web application with that data. With
+      this arrangement, you have the flexibility of messing up your data
+      in any way, knowing that whatever data changes you're making are only
+      being made to a test database.
+
+Note that this server does *not* automatically detect changes to your Python
+source code (as ``runserver`` does). It does, however, detect changes to
+templates.
+
+.. django-admin-option:: --addrport [port number or ipaddr:port]
+
+Use ``--addrport`` to specify a different port, or IP address and port, from
+the default of 127.0.0.1:8000. This value follows exactly the same format and
+serves exactly the same function as the argument to the ``runserver`` command.
+
+Examples:
+
+To run the test server on port 7000 with ``fixture1`` and ``fixture2``::
+
+    django-admin.py testserver --addrport 7000 fixture1 fixture2
+    django-admin.py testserver fixture1 fixture2 --addrport 7000
+
+(The above statements are equivalent. We include both of them to demonstrate
+that it doesn't matter whether the options come before or after the fixture
+arguments.)
+
+To run on 1.2.3.4:7000 with a ``test`` fixture::
+
+    django-admin.py testserver --addrport 1.2.3.4:7000 test
+
+validate
+--------
+
+.. django-admin:: validate
+
+Validates all installed models (according to the ``INSTALLED_APPS`` setting)
+and prints validation errors to standard output.
+
+Commands provided by applications
+=================================
+
+Some commands are only available when the ``django.contrib`` application that
+:doc:`implements </howto/custom-management-commands>` them has been
+:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by
+their application.
+
+``django.contrib.auth``
+-----------------------
+
+changepassword
+~~~~~~~~~~~~~~
+
+.. django-admin:: changepassword
+
+.. versionadded:: 1.2
+
+This command is only available if Django's :doc:`authentication system
+</topics/auth>` (``django.contrib.auth``) is installed.
+
+Allows changing a user's password. It prompts you to enter twice the password of
+the user given as parameter. If they both match, the new password will be
+changed immediately. If you do not supply a user, the command will attempt to
+change the password whose username matches the current user.
+
+Example usage::
+
+    django-admin.py changepassword ringo
+
+createsuperuser
+~~~~~~~~~~~~~~~
+
+.. django-admin:: createsuperuser
+
+.. versionadded:: 1.0
+
+This command is only available if Django's :doc:`authentication system
+</topics/auth>` (``django.contrib.auth``) is installed.
+
+Creates a superuser account (a user who has all permissions). This is
+useful if you need to create an initial superuser account but did not
+do so during ``syncdb``, or if you need to programmatically generate
+superuser accounts for your site(s).
+
+When run interactively, this command will prompt for a password for
+the new superuser account. When run non-interactively, no password
+will be set, and the superuser account will not be able to log in until
+a password has been manually set for it.
+
+.. django-admin-option:: --username
+.. django-admin-option:: --email
+
+The username and e-mail address for the new account can be supplied by
+using the ``--username`` and ``--email`` arguments on the command
+line. If either of those is not supplied, ``createsuperuser`` will prompt for
+it when running interactively.
+
+``django.contrib.gis``
+----------------------
+
+ogrinspect
+~~~~~~~~~~
+
+This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>`
+(``django.contrib.gis``) is installed.
+
+Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango
+documentation.
+
+``django.contrib.sitemaps``
+---------------------------
+
+ping_google
+~~~~~~~~~~~
+
+This command is only available if the :doc:`Sitemaps framework
+</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed.
+
+Please refer to its :djadmin:`description <ping_google>` in the Sitemaps
+documentation.
+
+Default options
+===============
+
+Although some commands may allow their own custom options, every command
+allows for the following options:
+
+.. django-admin-option:: --pythonpath
+
+Example usage::
+
+    django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject'
+
+Adds the given filesystem path to the Python `import search path`_. If this
+isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment
+variable.
+
+Note that this option is unnecessary in ``manage.py``, because it takes care of
+setting the Python path for you.
+
+.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
+
+.. django-admin-option:: --settings
+
+Example usage::
+
+    django-admin.py syncdb --settings=mysite.settings
+
+Explicitly specifies the settings module to use. The settings module should be
+in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
+``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment
+variable.
+
+Note that this option is unnecessary in ``manage.py``, because it uses
+``settings.py`` from the current project by default.
+
+.. django-admin-option:: --traceback
+
+Example usage::
+
+    django-admin.py syncdb --traceback
+
+By default, ``django-admin.py`` will show a simple error message whenever an
+error occurs. If you specify ``--traceback``, ``django-admin.py``  will
+output a full stack trace whenever an exception is raised.
+
+.. django-admin-option:: --verbosity
+
+Example usage::
+
+    django-admin.py syncdb --verbosity 2
+
+Use ``--verbosity`` to specify the amount of notification and debug information
+that ``django-admin.py`` should print to the console.
+
+    * ``0`` means no output.
+    * ``1`` means normal output (default).
+    * ``2`` means verbose output.
+
+Common options
+==============
+
+The following options are not available on every commands, but they are
+common to a number of commands.
+
+.. django-admin-option:: --database
+
+.. versionadded:: 1.2
+
+Used to specify the database on which a command will operate. If not
+specified, this option will default to an alias of ``default``.
+
+For example, to dump data from the database with the alias ``master``::
+
+    django-admin.py dumpdata --database=master
+
+.. django-admin-option:: --exclude
+
+Exclude a specific application from the applications whose contents is
+output. For example, to specifically exclude the `auth` application from
+the output of dumpdata, you would call::
+
+    django-admin.py dumpdata --exclude=auth
+
+If you want to exclude multiple applications, use multiple ``--exclude``
+directives::
+
+    django-admin.py dumpdata --exclude=auth --exclude=contenttypes
+
+.. django-admin-option:: --locale
+
+Use the ``--locale`` or ``-l`` option to specify the locale to process.
+If not provided all locales are processed.
+
+.. django-admin-option:: --noinput
+
+Use the ``--noinput`` option to suppress all user prompting, such as "Are
+you sure?" confirmation messages. This is useful if ``django-admin.py`` is
+being executed as an unattended, automated script.
+
+Extra niceties
+==============
+
+.. _syntax-coloring:
+
+Syntax coloring
+---------------
+
+The ``django-admin.py`` / ``manage.py`` commands will use pretty
+color-coded output if your terminal supports ANSI-colored output. It
+won't use the color codes if you're piping the command's output to
+another program.
+
+The colors used for syntax highlighting can be customized. Django
+ships with three color palettes:
+
+    * ``dark``, suited to terminals that show white text on a black
+      background. This is the default palette.
+
+    * ``light``, suited to terminals that show black text on a white
+      background.
+
+    * ``nocolor``, which disables syntax highlighting.
+
+You select a palette by setting a ``DJANGO_COLORS`` environment
+variable to specify the palette you want to use. For example, to
+specify the ``light`` palette under a Unix or OS/X BASH shell, you
+would run the following at a command prompt::
+
+    export DJANGO_COLORS="light"
+
+You can also customize the colors that are used. Django specifies a
+number of roles in which color is used:
+
+    * ``error`` - A major error.
+    * ``notice`` - A minor error.
+    * ``sql_field`` - The name of a model field in SQL.
+    * ``sql_coltype`` - The type of a model field in SQL.
+    * ``sql_keyword`` - A SQL keyword.
+    * ``sql_table`` - The name of a model in SQL.
+    * ``http_info`` - A 1XX HTTP Informational server response.
+    * ``http_success`` - A 2XX HTTP Success server response.
+    * ``http_not_modified`` - A 304 HTTP Not Modified server response.
+    * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304.
+    * ``http_not_found`` - A 404 HTTP Not Found server response.
+    * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404.
+    * ``http_server_error`` - A 5XX HTTP Server Error response.
+
+Each of these roles can be assigned a specific foreground and
+background color, from the following list:
+
+    * ``black``
+    * ``red``
+    * ``green``
+    * ``yellow``
+    * ``blue``
+    * ``magenta``
+    * ``cyan``
+    * ``white``
+
+Each of these colors can then be modified by using the following
+display options:
+
+    * ``bold``
+    * ``underscore``
+    * ``blink``
+    * ``reverse``
+    * ``conceal``
+
+A color specification follows one of the the following patterns:
+
+    * ``role=fg``
+    * ``role=fg/bg``
+    * ``role=fg,option,option``
+    * ``role=fg/bg,option,option``
+
+where ``role`` is the name of a valid color role, ``fg`` is the
+foreground color, ``bg`` is the background color and each ``option``
+is one of the color modifying options. Multiple color specifications
+are then separated by semicolon. For example::
+
+    export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta"
+
+would specify that errors be displayed using blinking yellow on blue,
+and notices displayed using magenta. All other color roles would be
+left uncolored.
+
+Colors can also be specified by extending a base palette. If you put
+a palette name in a color specification, all the colors implied by that
+palette will be loaded. So::
+
+    export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta"
+
+would specify the use of all the colors in the light color palette,
+*except* for the colors for errors and notices which would be
+overridden as specified.
+
+Bash completion
+---------------
+
+If you use the Bash shell, consider installing the Django bash completion
+script, which lives in ``extras/django_bash_completion`` in the Django
+distribution. It enables tab-completion of ``django-admin.py`` and
+``manage.py`` commands, so you can, for instance...
+
+    * Type ``django-admin.py``.
+    * Press [TAB] to see all available options.
+    * Type ``sql``, then [TAB], to see all available options whose names start
+      with ``sql``.
+
+
+See :doc:`/howto/custom-management-commands` for how to add customized actions.
+
+
+==========================================
+Running management commands from your code
+==========================================
+
+.. function:: django.core.management.call_command(name, *args, **options)
+
+To call a management command from code use ``call_command``.
+
+``name``
+  the name of the command to call.
+
+``*args``
+  a list of arguments accepted by the command.
+
+``**options``
+  named options accepted on the command-line.
+
+Examples::
+
+      from django.core import management
+      management.call_command('flush', verbosity=0, interactive=False)
+      management.call_command('loaddata', 'test_data', verbosity=0)
diff --git a/parts/django/docs/ref/exceptions.txt b/parts/django/docs/ref/exceptions.txt
new file mode 100644
index 0000000..f1246bf
--- /dev/null
+++ b/parts/django/docs/ref/exceptions.txt
@@ -0,0 +1,128 @@
+=================
+Django Exceptions
+=================
+
+
+Django raises some Django specific exceptions as well as many standard
+Python exceptions.
+
+Django-specific Exceptions
+==========================
+
+.. module:: django.core.exceptions
+    :synopsis: Django specific exceptions
+
+ObjectDoesNotExist and DoesNotExist
+-----------------------------------
+.. exception:: DoesNotExist
+.. exception:: ObjectDoesNotExist
+
+    The :exc:`DoesNotExist` exception is raised when an object is not found
+    for the given parameters of a query.
+
+    :exc:`ObjectDoesNotExist` is defined in :mod:`django.core.exceptions`.
+    :exc:`DoesNotExist` is a subclass of the base :exc:`ObjectDoesNotExist`
+    exception that is provided on every model class as a way of
+    identifying the specific type of object that could not be found.
+
+    See :meth:`~django.db.models.QuerySet.get()` for further information
+    on :exc:`ObjectDoesNotExist` and :exc:`DoesNotExist`.
+
+MultipleObjectsReturned
+-----------------------
+.. exception:: MultipleObjectsReturned
+
+    The :exc:`MultipleObjectsReturned` exception is raised by a query if only
+    one object is expected, but multiple objects are returned. A base version
+    of this exception is provided in :mod:`django.core.exceptions`; each model
+    class contains a subclassed version that can be used to identify the
+    specific object type that has returned multiple objects.
+
+    See :meth:`~django.db.models.QuerySet.get()` for further information.
+
+SuspiciousOperation
+-------------------
+.. exception:: SuspiciousOperation
+
+    The :exc:`SuspiciousOperation` exception is raised when a user has performed
+    an operation that should be considered suspicious from a security perspective,
+    such as tampering with a session cookie.
+
+PermissionDenied
+----------------
+.. exception:: PermissionDenied
+
+    The :exc:`PermissionDenied` exception is raised when a user does not have
+    permission to perform the action requested.
+
+ViewDoesNotExist
+----------------
+.. exception:: ViewDoesNotExist
+
+    The :exc:`ViewDoesNotExist` exception is raised by
+    :mod:`django.core.urlresolvers` when a requested view does not exist.
+
+MiddlewareNotUsed
+-----------------
+.. exception:: MiddlewareNotUsed
+
+    The :exc:`MiddlewareNotUsed` exception is raised when a middleware is not
+    used in the server configuration.
+
+ImproperlyConfigured
+--------------------
+.. exception:: ImproperlyConfigured
+
+    The :exc:`ImproperlyConfigured` exception is raised when Django is
+    somehow improperly configured -- for example, if a value in ``settings.py``
+    is incorrect or unparseable.
+
+FieldError
+----------
+.. exception:: FieldError
+
+    The :exc:`FieldError` exception is raised when there is a problem with a
+    model field. This can happen for several reasons:
+
+        - A field in a model clashes with a field of the same name from an
+          abstract base class
+        - An infinite loop is caused by ordering
+        - A keyword cannot be parsed from the filter parameters
+        - A field cannot be determined from a keyword in the query
+          parameters
+        - A join is not permitted on the specified field
+        - A field name is invalid
+        - A query contains invalid order_by arguments
+
+ValidationError
+---------------
+.. exception:: ValidationError
+
+    The :exc:`ValidationError` exception is raised when data fails form or
+    model field validation. For more information about validation, see
+    :doc:`Form and Field Validation </ref/forms/validation>`,
+    :ref:`Model Field Validation <validating-objects>` and the
+    :doc:`Validator Reference </ref/validators>`.
+
+Database Exceptions
+===================
+
+Django wraps the standard database exceptions :exc:`DatabaseError` and
+:exc:`IntegrityError` so that your Django code has a guaranteed common
+implementation of these classes. These database exceptions are
+provided in :mod:`django.db`.
+
+The Django wrappers for database exceptions behave exactly the same as
+the underlying database exceptions. See `PEP 249 - Python Database API
+Specification v2.0`_ for further information.
+
+.. _`PEP 249 - Python Database API Specification v2.0`: http://www.python.org/dev/peps/pep-0249/
+
+Python Exceptions
+=================
+
+Django raises built-in Python exceptions when appropriate as well. See
+the Python `documentation`_ for further information on the built-in
+exceptions.
+
+.. _`documentation`: http://docs.python.org/lib/module-exceptions.html
diff --git a/parts/django/docs/ref/files/file.txt b/parts/django/docs/ref/files/file.txt
new file mode 100644
index 0000000..1374d01
--- /dev/null
+++ b/parts/django/docs/ref/files/file.txt
@@ -0,0 +1,152 @@
+The ``File`` object
+===================
+
+The :mod:`django.core.files` module and its submodules contain built-in classes
+for basic file handling in Django.
+
+.. currentmodule:: django.core.files
+
+The ``File`` Class
+------------------
+
+.. class:: File(file_object)
+
+    The :class:`File` is a thin wrapper around Python's built-in file object
+    with some Django-specific additions. Internally, Django uses this class
+    any time it needs to represent a file.
+    
+    :class:`File` objects have the following attributes and methods:
+
+    .. attribute:: name
+
+        The name of file including the relative path from
+        :setting:`MEDIA_ROOT`.
+
+    .. attribute:: size
+
+        The size of the file in bytes.
+
+    .. attribute:: file
+
+        The underlying Python ``file`` object passed to
+        :class:`~django.core.files.File`.
+
+    .. attribute:: mode
+
+        The read/write mode for the file.
+
+    .. method:: open([mode=None])
+
+        Open or reopen the file (which by definition also does
+        ``File.seek(0)``). The ``mode`` argument allows the same values
+        as Python's standard ``open()``.
+
+        When reopening a file, ``mode`` will override whatever mode the file
+        was originally opened with; ``None`` means to reopen with the original
+        mode.
+
+    .. method:: read([num_bytes=None])
+
+        Read content from the file. The optional ``size`` is the number of
+        bytes to read; if not specified, the file will be read to the end.
+
+    .. method:: __iter__()
+
+        Iterate over the file yielding one line at a time.
+
+    .. method:: chunks([chunk_size=None])
+
+        Iterate over the file yielding "chunks" of a given size. ``chunk_size``
+        defaults to 64 KB.
+
+        This is especially useful with very large files since it allows them to
+        be streamed off disk and avoids storing the whole file in memory.
+
+    .. method:: multiple_chunks([chunk_size=None])
+
+        Returns ``True`` if the file is large enough to require multiple chunks
+        to access all of its content give some ``chunk_size``.
+
+    .. method:: write([content])
+
+        Writes the specified content string to the file. Depending on the
+        storage system behind the scenes, this content might not be fully
+        committed until ``close()`` is called on the file.
+
+    .. method:: close()
+
+        Close the file.
+
+    In addition to the listed methods, :class:`~django.core.files.File` exposes
+    the following attributes and methods of the underlying ``file`` object:
+    ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``,
+    ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``,
+    ``truncate``, ``writelines``, ``xreadlines``.
+
+.. currentmodule:: django.core.files.base
+
+The ``ContentFile`` Class
+-------------------------
+
+.. class:: ContentFile(File)
+
+    The ``ContentFile`` class inherits from :class:`~django.core.files.File`,
+    but unlike :class:`~django.core.files.File` it operates on string content,
+    rather than an actual file. For example::
+
+        from django.core.files.base import ContentFile
+
+        f1 = ContentFile("my string content")
+        f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
+
+.. currentmodule:: django.core.files.images
+
+The ``ImageFile`` Class
+-----------------------
+
+.. class:: ImageFile(file_object)
+
+    Django provides a built-in class specifically for images.
+    :class:`django.core.files.images.ImageFile` inherits all the attributes
+    and methods of :class:`~django.core.files.File`, and additionally
+    provides the following:
+
+    .. attribute:: width
+
+        Width of the image in pixels.
+
+    .. attribute:: height
+
+        Height of the image in pixels.
+
+.. currentmodule:: django.core.files
+
+Additional methods on files attached to objects
+-----------------------------------------------
+
+Any :class:`File` that's associated with an object (as with ``Car.photo``,
+below) will also have a couple of extra methods:
+
+.. method:: File.save(name, content, [save=True])
+
+    Saves a new file with the file name and contents provided. This will not
+    replace the existing file, but will create a new file and update the object
+    to point to it. If ``save`` is ``True``, the model's ``save()`` method will
+    be called once the file is saved. That is, these two lines::
+
+        >>> car.photo.save('myphoto.jpg', contents, save=False)
+        >>> car.save()
+
+    are the same as this one line::
+
+        >>> car.photo.save('myphoto.jpg', contents, save=True)
+
+    Note that the ``content`` argument must be an instance of either
+    :class:`File` or of a subclass of :class:`File`, such as
+    :class:`ContentFile`.
+
+.. method:: File.delete([save=True])
+
+    Removes the file from the model instance and deletes the underlying file.
+    If ``save`` is ``True``, the model's ``save()`` method will be called once
+    the file is deleted.
diff --git a/parts/django/docs/ref/files/index.txt b/parts/django/docs/ref/files/index.txt
new file mode 100644
index 0000000..552559d
--- /dev/null
+++ b/parts/django/docs/ref/files/index.txt
@@ -0,0 +1,12 @@
+=============
+File handling
+=============
+
+.. module:: django.core.files
+   :synopsis: File handling and storage
+
+.. toctree::
+   :maxdepth: 2
+
+   file
+   storage
diff --git a/parts/django/docs/ref/files/storage.txt b/parts/django/docs/ref/files/storage.txt
new file mode 100644
index 0000000..84ef00c
--- /dev/null
+++ b/parts/django/docs/ref/files/storage.txt
@@ -0,0 +1,119 @@
+File storage API
+================
+
+.. module:: django.core.files.storage
+
+Getting the current storage class
+---------------------------------
+
+Django provides two convenient ways to access the current storage class:
+
+.. class:: DefaultStorage
+
+    :class:`~django.core.files.storage.DefaultStorage` provides
+    lazy access to the current default storage system as defined by
+    :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses
+    :func:`~django.core.files.storage.get_storage_class` internally.
+
+.. function:: get_storage_class([import_path=None])
+
+    Returns a class or module which implements the storage API.
+    
+    When called without the ``import_path`` parameter ``get_storage_class``
+    will return the current default storage system as defined by
+    :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided,
+    ``get_storage_class`` will attempt to import the class or module from the
+    given path and will return it if successful. An exception will be
+    raised if the import is unsuccessful.
+
+The FileSystemStorage Class
+---------------------------
+
+.. class:: FileSystemStorage
+
+    The :class:`~django.core.files.storage.FileSystemStorage` class implements
+    basic file storage on a local filesystem. It inherits from
+    :class:`~django.core.files.storage.Storage` and provides implementations
+    for all the public methods thereof.
+    
+    .. note::
+    
+        The :class:`FileSystemStorage.delete` method will not raise
+        raise an exception if the given file name does not exist.
+
+The Storage Class
+-----------------
+
+.. class:: Storage
+
+    The :class:`~django.core.files.storage.Storage` class provides a
+    standardized API for storing files, along with a set of default
+    behaviors that all other storage systems can inherit or override
+    as necessary.
+
+    .. method:: delete(name)
+
+        Deletes the file referenced by ``name``. If deletion is not supported
+        on the targest storage system this will raise ``NotImplementedError``
+        instead
+
+    .. method:: exists(name)
+
+        Returns ``True`` if a file referened by the given name already exists
+        in the storage system, or ``False`` if the name is available for a new
+        file.
+
+    .. method:: get_available_name(name)
+
+        Returns a filename based on the ``name`` parameter that's free and
+        available for new content to be written to on the target storage
+        system.
+
+
+    .. method:: get_valid_name(name)
+
+        Returns a filename based on the ``name`` parameter that's suitable
+        for use on the target storage system.
+
+    .. method:: listdir(path)
+
+        Lists the contents of the specified path, returning a 2-tuple of lists;
+        the first item being directories, the second item being files. For
+        storage systems that aren't able to provide such a listing, this will
+        raise a ``NotImplementedError`` instead.
+
+    .. method:: open(name, mode='rb')
+
+        Opens the file given by ``name``. Note that although the returned file
+        is guaranteed to be a ``File`` object, it might actually be some
+        subclass. In the case of remote file storage this means that
+        reading/writing could be quite slow, so be warned.
+
+    .. method:: path(name)
+
+        The local filesystem path where the file can be opened using Python's
+        standard ``open()``. For storage systems that aren't accessible from
+        the local filesystem, this will raise ``NotImplementedError`` instead.
+
+    .. method:: save(name, content)
+
+        Saves a new file using the storage system, preferably with the name
+        specified. If there already exists a file with this name ``name``, the
+        storage system may modify the filename as necessary to get a unique
+        name. The actual name of the stored file will be returned.
+
+        The ``content`` argument must be an instance of
+        :class:`django.core.files.File` or of a subclass of
+        :class:`~django.core.files.File`.
+
+    .. method:: size(name)
+
+        Returns the total size, in bytes, of the file referenced by ``name``.
+        For storage systems that aren't able to return the file size this will
+        raise ``NotImplementedError`` instead.
+
+    .. method:: url(name)
+
+        Returns the URL where the contents of the file referenced by ``name``
+        can be accessed. For storage systems that don't support access by URL
+        this will raise ``NotImplementedError`` instead.
diff --git a/parts/django/docs/ref/forms/api.txt b/parts/django/docs/ref/forms/api.txt
new file mode 100644
index 0000000..613d754
--- /dev/null
+++ b/parts/django/docs/ref/forms/api.txt
@@ -0,0 +1,791 @@
+=============
+The Forms API
+=============
+
+.. module:: django.forms.forms
+
+.. currentmodule:: django.forms
+
+.. admonition:: About this document
+
+    This document covers the gritty details of Django's forms API. You should
+    read the :doc:`introduction to working with forms </topics/forms/index>`
+    first.
+
+.. _ref-forms-api-bound-unbound:
+
+Bound and unbound forms
+-----------------------
+
+A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
+
+    * If it's **bound** to a set of data, it's capable of validating that data
+      and rendering the form as HTML with the data displayed in the HTML.
+
+    * If it's **unbound**, it cannot do validation (because there's no data to
+      validate!), but it can still render the blank form as HTML.
+
+.. class:: Form
+
+To create an unbound :class:`Form` instance, simply instantiate the class::
+
+    >>> f = ContactForm()
+
+To bind data to a form, pass the data as a dictionary as the first parameter to
+your :class:`Form` class constructor::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+
+In this dictionary, the keys are the field names, which correspond to the
+attributes in your :class:`Form` class. The values are the data you're trying to
+validate. These will usually be strings, but there's no requirement that they be
+strings; the type of data you pass depends on the :class:`Field`, as we'll see
+in a moment.
+
+.. attribute:: Form.is_bound
+
+If you need to distinguish between bound and unbound form instances at runtime,
+check the value of the form's :attr:`~Form.is_bound` attribute::
+
+    >>> f = ContactForm()
+    >>> f.is_bound
+    False
+    >>> f = ContactForm({'subject': 'hello'})
+    >>> f.is_bound
+    True
+
+Note that passing an empty dictionary creates a *bound* form with empty data::
+
+    >>> f = ContactForm({})
+    >>> f.is_bound
+    True
+
+If you have a bound :class:`Form` instance and want to change the data somehow,
+or if you want to bind an unbound :class:`Form` instance to some data, create
+another :class:`Form` instance. There is no way to change data in a
+:class:`Form` instance. Once a :class:`Form` instance has been created, you
+should consider its data immutable, whether it has data or not.
+
+Using forms to validate data
+----------------------------
+
+.. method:: Form.is_valid()
+
+The primary task of a :class:`Form` object is to validate data. With a bound
+:class:`Form` instance, call the :meth:`~Form.is_valid` method to run validation
+and return a boolean designating whether the data was valid::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    True
+
+Let's try with some invalid data. In this case, ``subject`` is blank (an error,
+because all fields are required by default) and ``sender`` is not a valid
+e-mail address::
+
+    >>> data = {'subject': '',
+    ...         'message': 'Hi there',
+    ...         'sender': 'invalid e-mail address',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    False
+
+.. attribute:: Form.errors
+
+Access the :attr:`~Form.errors` attribute to get a dictionary of error
+messages::
+
+    >>> f.errors
+    {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']}
+
+In this dictionary, the keys are the field names, and the values are lists of
+Unicode strings representing the error messages. The error messages are stored
+in lists because a field can have multiple error messages.
+
+You can access :attr:`~Form.errors` without having to call
+:meth:`~Form.is_valid` first. The form's data will be validated the first time
+either you call :meth:`~Form.is_valid` or access :attr:`~Form.errors`.
+
+The validation routines will only get called once, regardless of how many times
+you access :attr:`~Form.errors` or call :meth:`~Form.is_valid`. This means that
+if validation has side effects, those side effects will only be triggered once.
+
+Behavior of unbound forms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's meaningless to validate a form with no data, but, for the record, here's
+what happens with unbound forms::
+
+    >>> f = ContactForm()
+    >>> f.is_valid()
+    False
+    >>> f.errors
+    {}
+
+Dynamic initial values
+----------------------
+
+.. attribute:: Form.initial
+
+Use :attr:`~Form.initial` to declare the initial value of form fields at
+runtime. For example, you might want to fill in a ``username`` field with the
+username of the current session.
+
+To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`.
+This argument, if given, should be a dictionary mapping field names to initial
+values. Only include the fields for which you're specifying an initial value;
+it's not necessary to include every field in your form. For example::
+
+    >>> f = ContactForm(initial={'subject': 'Hi there!'})
+
+These values are only displayed for unbound forms, and they're not used as
+fallback values if a particular value isn't provided.
+
+Note that if a :class:`~django.forms.fields.Field` defines
+:attr:`~Form.initial` *and* you include ``initial`` when instantiating the
+``Form``, then the latter ``initial`` will have precedence. In this example,
+``initial`` is provided both at the field level and at the form instance level,
+and the latter gets precedence::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField(initial='class')
+    ...     url = forms.URLField()
+    ...     comment = forms.CharField()
+    >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
+    >>> print f
+    <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
+    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
+
+Accessing "clean" data
+----------------------
+
+.. attribute:: Form.cleaned_data
+
+Each field in a :class:`Form` class is responsible not only for validating
+data, but also for "cleaning" it -- normalizing it to a consistent format. This
+is a nice feature, because it allows data for a particular field to be input in
+a variety of ways, always resulting in consistent output.
+
+For example, :class:`~django.forms.DateField` normalizes input into a
+Python ``datetime.date`` object. Regardless of whether you pass it a string in
+the format ``'1994-07-15'``, a ``datetime.date`` object, or a number of other
+formats, ``DateField`` will always normalize it to a ``datetime.date`` object
+as long as it's valid.
+
+Once you've created a :class:`~Form` instance with a set of data and validated
+it, you can access the clean data via its ``cleaned_data`` attribute::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    True
+    >>> f.cleaned_data
+    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
+
+.. versionchanged:: 1.0
+    The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases.
+
+Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
+always cleans the input into a Unicode string. We'll cover the encoding
+implications later in this document.
+
+If your data does *not* validate, your ``Form`` instance will not have a
+``cleaned_data`` attribute::
+
+    >>> data = {'subject': '',
+    ...         'message': 'Hi there',
+    ...         'sender': 'invalid e-mail address',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    False
+    >>> f.cleaned_data
+    Traceback (most recent call last):
+    ...
+    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
+
+``cleaned_data`` will always *only* contain a key for fields defined in the
+``Form``, even if you pass extra data when you define the ``Form``. In this
+example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
+but ``cleaned_data`` contains only the form's fields::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True,
+    ...         'extra_field_1': 'foo',
+    ...         'extra_field_2': 'bar',
+    ...         'extra_field_3': 'baz'}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    True
+    >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
+    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
+
+``cleaned_data`` will include a key and value for *all* fields defined in the
+``Form``, even if the data didn't include a value for fields that are not
+required. In this example, the data dictionary doesn't include a value for the
+``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
+
+    >>> class OptionalPersonForm(Form):
+    ...     first_name = CharField()
+    ...     last_name = CharField()
+    ...     nick_name = CharField(required=False)
+    >>> data = {'first_name': u'John', 'last_name': u'Lennon'}
+    >>> f = OptionalPersonForm(data)
+    >>> f.is_valid()
+    True
+    >>> f.cleaned_data
+    {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
+
+In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
+empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
+empty values as an empty string. Each field type knows what its "blank" value
+is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
+full details on each field's behavior in this case, see the "Empty value" note
+for each field in the "Built-in ``Field`` classes" section below.
+
+You can write code to perform validation for particular form fields (based on
+their name) or for the form as a whole (considering combinations of various
+fields). More information about this is in :doc:`/ref/forms/validation`.
+
+Outputting forms as HTML
+------------------------
+
+The second task of a ``Form`` object is to render itself as HTML. To do so,
+simply ``print`` it::
+
+    >>> f = ContactForm()
+    >>> print f
+    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
+    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
+    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
+    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
+
+If the form is bound to data, the HTML output will include that data
+appropriately. For example, if a field is represented by an
+``<input type="text">``, the data will be in the ``value`` attribute. If a
+field is represented by an ``<input type="checkbox">``, then that HTML will
+include ``checked="checked"`` if appropriate::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> print f
+    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr>
+    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr>
+    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr>
+    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr>
+
+This default output is a two-column HTML table, with a ``<tr>`` for each field.
+Notice the following:
+
+    * For flexibility, the output does *not* include the ``<table>`` and
+      ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
+      tags or an ``<input type="submit">`` tag. It's your job to do that.
+
+    * Each field type has a default HTML representation. ``CharField`` and
+      ``EmailField`` are represented by an ``<input type="text">``.
+      ``BooleanField`` is represented by an ``<input type="checkbox">``. Note
+      these are merely sensible defaults; you can specify which HTML to use for
+      a given field by using widgets, which we'll explain shortly.
+
+    * The HTML ``name`` for each tag is taken directly from its attribute name
+      in the ``ContactForm`` class.
+
+    * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and
+      ``'Cc myself:'`` is generated from the field name by converting all
+      underscores to spaces and upper-casing the first letter. Again, note
+      these are merely sensible defaults; you can also specify labels manually.
+
+    * Each text label is surrounded in an HTML ``<label>`` tag, which points
+      to the appropriate form field via its ``id``. Its ``id``, in turn, is
+      generated by prepending ``'id_'`` to the field name. The ``id``
+      attributes and ``<label>`` tags are included in the output by default, to
+      follow best practices, but you can change that behavior.
+
+Although ``<table>`` output is the default output style when you ``print`` a
+form, other output styles are available. Each style is available as a method on
+a form object, and each rendering method returns a Unicode object.
+
+``as_p()``
+~~~~~~~~~~
+
+.. method:: Form.as_p
+
+    ``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
+    containing one field::
+
+        >>> f = ContactForm()
+        >>> f.as_p()
+        u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'
+        >>> print f.as_p()
+        <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>
+        <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>
+        <p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>
+        <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
+
+``as_ul()``
+~~~~~~~~~~~
+
+.. method:: Form.as_ul
+
+    ``as_ul()`` renders the form as a series of ``<li>`` tags, with each
+    ``<li>`` containing one field. It does *not* include the ``<ul>`` or
+    ``</ul>``, so that you can specify any HTML attributes on the ``<ul>`` for
+    flexibility::
+
+        >>> f = ContactForm()
+        >>> f.as_ul()
+        u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'
+        >>> print f.as_ul()
+        <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>
+        <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>
+        <li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>
+        <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
+
+``as_table()``
+~~~~~~~~~~~~~~
+
+.. method:: Form.as_table
+
+    Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is
+    exactly the same as ``print``. In fact, when you ``print`` a form object,
+    it calls its ``as_table()`` method behind the scenes::
+
+        >>> f = ContactForm()
+        >>> f.as_table()
+        u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'
+        >>> print f.as_table()
+        <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
+        <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
+        <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
+        <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
+
+Styling required or erroneous form rows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+It's pretty common to style form rows and fields that are required or have
+errors. For example, you might want to present required form rows in bold and
+highlight errors in red.
+
+The :class:`Form` class has a couple of hooks you can use to add ``class``
+attributes to required rows or to rows with errors: simple set the
+:attr:`Form.error_css_class` and/or :attr:`Form.required_css_class`
+attributes::
+
+    class ContactForm(Form):
+        error_css_class = 'error'
+        required_css_class = 'required'
+
+        # ... and the rest of your fields here
+
+Once you've done that, rows will be given ``"error"`` and/or ``"required"``
+classes, as needed. The HTML will look something like::
+
+    >>> f = ContactForm(data)
+    >>> print f.as_table()
+    <tr class="required"><th><label for="id_subject">Subject:</label>    ...
+    <tr class="required"><th><label for="id_message">Message:</label>    ...
+    <tr class="required error"><th><label for="id_sender">Sender:</label>      ...
+    <tr><th><label for="id_cc_myself">Cc myself:<label> ...
+
+.. _ref-forms-api-configuring-label:
+
+Configuring HTML ``<label>`` tags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An HTML ``<label>`` tag designates which label text is associated with which
+form element. This small enhancement makes forms more usable and more accessible
+to assistive devices. It's always a good idea to use ``<label>`` tags.
+
+By default, the form rendering methods include HTML ``id`` attributes on the
+form elements and corresponding ``<label>`` tags around the labels. The ``id``
+attribute values are generated by prepending ``id_`` to the form field names.
+This behavior is configurable, though, if you want to change the ``id``
+convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
+
+Use the ``auto_id`` argument to the ``Form`` constructor to control the label
+and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
+
+If ``auto_id`` is ``False``, then the form output will not include ``<label>``
+tags nor ``id`` attributes::
+
+    >>> f = ContactForm(auto_id=False)
+    >>> print f.as_table()
+    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr>
+    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
+    <tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr>
+    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
+    >>> print f.as_ul()
+    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
+    <li>Message: <input type="text" name="message" /></li>
+    <li>Sender: <input type="text" name="sender" /></li>
+    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
+    >>> print f.as_p()
+    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
+    <p>Message: <input type="text" name="message" /></p>
+    <p>Sender: <input type="text" name="sender" /></p>
+    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
+
+If ``auto_id`` is set to ``True``, then the form output *will* include
+``<label>`` tags and will simply use the field name as its ``id`` for each form
+field::
+
+    >>> f = ContactForm(auto_id=True)
+    >>> print f.as_table()
+    <tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr>
+    <tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr>
+    <tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr>
+    <tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr>
+    >>> print f.as_ul()
+    <li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li>
+    <li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li>
+    <li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li>
+    <li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li>
+    >>> print f.as_p()
+    <p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p>
+    <p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p>
+    <p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p>
+    <p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p>
+
+If ``auto_id`` is set to a string containing the format character ``'%s'``,
+then the form output will include ``<label>`` tags, and will generate ``id``
+attributes based on the format string. For example, for a format string
+``'field_%s'``, a field named ``subject`` will get the ``id`` value
+``'field_subject'``. Continuing our example::
+
+    >>> f = ContactForm(auto_id='id_for_%s')
+    >>> print f.as_table()
+    <tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr>
+    <tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr>
+    <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr>
+    <tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr>
+    >>> print f.as_ul()
+    <li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
+    <li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li>
+    <li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li>
+    <li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
+    >>> print f.as_p()
+    <p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p>
+    <p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p>
+    <p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p>
+    <p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p>
+
+If ``auto_id`` is set to any other true value -- such as a string that doesn't
+include ``%s`` -- then the library will act as if ``auto_id`` is ``True``.
+
+By default, ``auto_id`` is set to the string ``'id_%s'``.
+
+Normally, a colon (``:``) will be appended after any label name when a form is
+rendered. It's possible to change the colon to another character, or omit it
+entirely, using the ``label_suffix`` parameter::
+
+    >>> f = ContactForm(auto_id='id_for_%s', label_suffix='')
+    >>> print f.as_ul()
+    <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
+    <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li>
+    <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li>
+    <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
+    >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->')
+    >>> print f.as_ul()
+    <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
+    <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li>
+    <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li>
+    <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
+
+Note that the label suffix is added only if the last character of the
+label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``)
+
+Notes on field ordering
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
+displayed in the order in which you define them in your form class. For
+example, in the ``ContactForm`` example, the fields are defined in the order
+``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
+output, just change the order in which those fields are listed in the class.
+
+How errors are displayed
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you render a bound ``Form`` object, the act of rendering will automatically
+run the form's validation if it hasn't already happened, and the HTML output
+will include the validation errors as a ``<ul class="errorlist">`` near the
+field. The particular positioning of the error messages depends on the output
+method you're using::
+
+    >>> data = {'subject': '',
+    ...         'message': 'Hi there',
+    ...         'sender': 'invalid e-mail address',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data, auto_id=False)
+    >>> print f.as_table()
+    <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr>
+    <tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr>
+    <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr>
+    <tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr>
+    >>> print f.as_ul()
+    <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li>
+    <li>Message: <input type="text" name="message" value="Hi there" /></li>
+    <li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li>
+    <li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li>
+    >>> print f.as_p()
+    <p><ul class="errorlist"><li>This field is required.</li></ul></p>
+    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
+    <p>Message: <input type="text" name="message" value="Hi there" /></p>
+    <p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p>
+    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
+    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
+
+Customizing the error list format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, forms use ``django.forms.util.ErrorList`` to format validation
+errors. If you'd like to use an alternate class for displaying errors, you can
+pass that in at construction time::
+
+    >>> from django.forms.util import ErrorList
+    >>> class DivErrorList(ErrorList):
+    ...     def __unicode__(self):
+    ...         return self.as_divs()
+    ...     def as_divs(self):
+    ...         if not self: return u''
+    ...         return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
+    >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
+    >>> f.as_p()
+    <div class="errorlist"><div class="error">This field is required.</div></div>
+    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
+    <p>Message: <input type="text" name="message" value="Hi there" /></p>
+    <div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div>
+    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
+    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
+
+More granular output
+~~~~~~~~~~~~~~~~~~~~
+
+The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
+lazy developers -- they're not the only way a form object can be displayed.
+
+To display the HTML for a single field in your form, use dictionary lookup
+syntax using the field's name as the key, and print the resulting object::
+
+    >>> f = ContactForm()
+    >>> print f['subject']
+    <input id="id_subject" type="text" name="subject" maxlength="100" />
+    >>> print f['message']
+    <input type="text" name="message" id="id_message" />
+    >>> print f['sender']
+    <input type="text" name="sender" id="id_sender" />
+    >>> print f['cc_myself']
+    <input type="checkbox" name="cc_myself" id="id_cc_myself" />
+
+Call ``str()`` or ``unicode()`` on the field to get its rendered HTML as a
+string or Unicode object, respectively::
+
+    >>> str(f['subject'])
+    '<input id="id_subject" type="text" name="subject" maxlength="100" />'
+    >>> unicode(f['subject'])
+    u'<input id="id_subject" type="text" name="subject" maxlength="100" />'
+
+Form objects define a custom ``__iter__()`` method, which allows you to loop
+through their fields::
+
+    >>> f = ContactForm()
+    >>> for field in f: print field
+    <input id="id_subject" type="text" name="subject" maxlength="100" />
+    <input type="text" name="message" id="id_message" />
+    <input type="text" name="sender" id="id_sender" />
+    <input type="checkbox" name="cc_myself" id="id_cc_myself" />
+
+The field-specific output honors the form object's ``auto_id`` setting::
+
+    >>> f = ContactForm(auto_id=False)
+    >>> print f['message']
+    <input type="text" name="message" />
+    >>> f = ContactForm(auto_id='id_%s')
+    >>> print f['message']
+    <input type="text" name="message" id="id_message" />
+
+For a field's list of errors, access the field's ``errors`` attribute. This
+is a list-like object that is displayed as an HTML ``<ul class="errorlist">``
+when printed::
+
+    >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
+    >>> f = ContactForm(data, auto_id=False)
+    >>> print f['message']
+    <input type="text" name="message" />
+    >>> f['message'].errors
+    [u'This field is required.']
+    >>> print f['message'].errors
+    <ul class="errorlist"><li>This field is required.</li></ul>
+    >>> f['subject'].errors
+    []
+    >>> print f['subject'].errors
+
+    >>> str(f['subject'].errors)
+    ''
+
+.. versionadded:: 1.2
+
+When you use Django's rendering shortcuts, CSS classes are used to
+indicate required form fields or fields that contain errors. If you're
+manually rendering a form, you can access these CSS classes using the
+``css_classes`` method::
+
+	>>> f = ContactForm(data)
+	>>> f['message'].css_classes()
+	'required'
+
+If you want to provide some additional classes in addition to the
+error and required classes that may be required, you can provide
+those classes as an argument::
+
+	>>> f = ContactForm(data)
+	>>> f['message'].css_classes('foo bar')
+	'foo bar required'
+
+.. _binding-uploaded-files:
+
+Binding uploaded files to a form
+--------------------------------
+
+.. versionadded:: 1.0
+
+Dealing with forms that have ``FileField`` and ``ImageField`` fields
+is a little more complicated than a normal form.
+
+Firstly, in order to upload files, you'll need to make sure that your
+``<form>`` element correctly defines the ``enctype`` as
+``"multipart/form-data"``::
+
+  <form enctype="multipart/form-data" method="post" action="/foo/">
+
+Secondly, when you use the form, you need to bind the file data. File
+data is handled separately to normal form data, so when your form
+contains a ``FileField`` and ``ImageField``, you will need to specify
+a second argument when you bind your form. So if we extend our
+ContactForm to include an ``ImageField`` called ``mugshot``, we
+need to bind the file data containing the mugshot image::
+
+    # Bound form with an image field
+    >>> from django.core.files.uploadedfile import SimpleUploadedFile
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
+    >>> f = ContactFormWithMugshot(data, file_data)
+
+In practice, you will usually specify ``request.FILES`` as the source
+of file data (just like you use ``request.POST`` as the source of
+form data)::
+
+    # Bound form with an image field, data from the request
+    >>> f = ContactFormWithMugshot(request.POST, request.FILES)
+
+Constructing an unbound form is the same as always -- just omit both
+form data *and* file data::
+
+    # Unbound form with a image field
+    >>> f = ContactFormWithMugshot()
+
+Testing for multipart forms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're writing reusable views or templates, you may not know ahead of time
+whether your form is a multipart form or not. The ``is_multipart()`` method
+tells you whether the form requires multipart encoding for submission::
+
+    >>> f = ContactFormWithMugshot()
+    >>> f.is_multipart()
+    True
+
+Here's an example of how you might use this in a template::
+
+    {% if form.is_multipart %}
+        <form enctype="multipart/form-data" method="post" action="/foo/">
+    {% else %}
+        <form method="post" action="/foo/">
+    {% endif %}
+    {{ form }}
+    </form>
+
+Subclassing forms
+-----------------
+
+If you have multiple ``Form`` classes that share fields, you can use
+subclassing to remove redundancy.
+
+When you subclass a custom ``Form`` class, the resulting subclass will
+include all fields of the parent class(es), followed by the fields you define
+in the subclass.
+
+In this example, ``ContactFormWithPriority`` contains all the fields from
+``ContactForm``, plus an additional field, ``priority``. The ``ContactForm``
+fields are ordered first::
+
+    >>> class ContactFormWithPriority(ContactForm):
+    ...     priority = forms.CharField()
+    >>> f = ContactFormWithPriority(auto_id=False)
+    >>> print f.as_ul()
+    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
+    <li>Message: <input type="text" name="message" /></li>
+    <li>Sender: <input type="text" name="sender" /></li>
+    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
+    <li>Priority: <input type="text" name="priority" /></li>
+
+It's possible to subclass multiple forms, treating forms as "mix-ins." In this
+example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm``
+(in that order), and its field list includes the fields from the parent
+classes::
+
+    >>> class PersonForm(Form):
+    ...     first_name = CharField()
+    ...     last_name = CharField()
+    >>> class InstrumentForm(Form):
+    ...     instrument = CharField()
+    >>> class BeatleForm(PersonForm, InstrumentForm):
+    ...     haircut_type = CharField()
+    >>> b = BeatleForm(auto_id=False)
+    >>> print b.as_ul()
+    <li>First name: <input type="text" name="first_name" /></li>
+    <li>Last name: <input type="text" name="last_name" /></li>
+    <li>Instrument: <input type="text" name="instrument" /></li>
+    <li>Haircut type: <input type="text" name="haircut_type" /></li>
+
+.. _form-prefix:
+
+Prefixes for forms
+------------------
+
+.. attribute:: Form.prefix
+
+You can put several Django forms inside one ``<form>`` tag. To give each
+``Form`` its own namespace, use the ``prefix`` keyword argument::
+
+    >>> mother = PersonForm(prefix="mother")
+    >>> father = PersonForm(prefix="father")
+    >>> print mother.as_ul()
+    <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
+    <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
+    >>> print father.as_ul()
+    <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
+    <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>
diff --git a/parts/django/docs/ref/forms/fields.txt b/parts/django/docs/ref/forms/fields.txt
new file mode 100644
index 0000000..91f245a
--- /dev/null
+++ b/parts/django/docs/ref/forms/fields.txt
@@ -0,0 +1,939 @@
+===========
+Form fields
+===========
+
+.. module:: django.forms.fields
+   :synopsis: Django's built-in form fields.
+
+.. currentmodule:: django.forms
+
+.. class:: Field(**kwargs)
+
+When you create a ``Form`` class, the most important part is defining the
+fields of the form. Each field has custom validation logic, along with a few
+other hooks.
+
+.. method:: Field.clean(value)
+
+Although the primary way you'll use ``Field`` classes is in ``Form`` classes,
+you can also instantiate them and use them directly to get a better idea of
+how they work. Each ``Field`` instance has a ``clean()`` method, which takes
+a single argument and either raises a ``django.forms.ValidationError``
+exception or returns the clean value::
+
+    >>> from django import forms
+    >>> f = forms.EmailField()
+    >>> f.clean('foo@example.com')
+    u'foo@example.com'
+    >>> f.clean(u'foo@example.com')
+    u'foo@example.com'
+    >>> f.clean('invalid e-mail address')
+    Traceback (most recent call last):
+    ...
+    ValidationError: [u'Enter a valid e-mail address.']
+
+Core field arguments
+--------------------
+
+Each ``Field`` class constructor takes at least these arguments. Some
+``Field`` classes take additional, field-specific arguments, but the following
+should *always* be accepted:
+
+``required``
+~~~~~~~~~~~~
+
+.. attribute:: Field.required
+
+By default, each ``Field`` class assumes the value is required, so if you pass
+an empty value -- either ``None`` or the empty string (``""``) -- then
+``clean()`` will raise a ``ValidationError`` exception::
+
+    >>> f = forms.CharField()
+    >>> f.clean('foo')
+    u'foo'
+    >>> f.clean('')
+    Traceback (most recent call last):
+    ...
+    ValidationError: [u'This field is required.']
+    >>> f.clean(None)
+    Traceback (most recent call last):
+    ...
+    ValidationError: [u'This field is required.']
+    >>> f.clean(' ')
+    u' '
+    >>> f.clean(0)
+    u'0'
+    >>> f.clean(True)
+    u'True'
+    >>> f.clean(False)
+    u'False'
+
+To specify that a field is *not* required, pass ``required=False`` to the
+``Field`` constructor::
+
+    >>> f = forms.CharField(required=False)
+    >>> f.clean('foo')
+    u'foo'
+    >>> f.clean('')
+    u''
+    >>> f.clean(None)
+    u''
+    >>> f.clean(0)
+    u'0'
+    >>> f.clean(True)
+    u'True'
+    >>> f.clean(False)
+    u'False'
+
+If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value,
+then ``clean()`` will return a *normalized* empty value rather than raising
+``ValidationError``. For ``CharField``, this will be a Unicode empty string.
+For other ``Field`` classes, it might be ``None``. (This varies from field to
+field.)
+
+``label``
+~~~~~~~~~
+
+.. attribute:: Field.label
+
+The ``label`` argument lets you specify the "human-friendly" label for this
+field. This is used when the ``Field`` is displayed in a ``Form``.
+
+As explained in "Outputting forms as HTML" above, the default label for a
+``Field`` is generated from the field name by converting all underscores to
+spaces and upper-casing the first letter. Specify ``label`` if that default
+behavior doesn't result in an adequate label.
+
+Here's a full example ``Form`` that implements ``label`` for two of its fields.
+We've specified ``auto_id=False`` to simplify the output::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField(label='Your name')
+    ...     url = forms.URLField(label='Your Web site', required=False)
+    ...     comment = forms.CharField()
+    >>> f = CommentForm(auto_id=False)
+    >>> print f
+    <tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
+    <tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
+
+``initial``
+~~~~~~~~~~~
+
+.. attribute:: Field.initial
+
+The ``initial`` argument lets you specify the initial value to use when
+rendering this ``Field`` in an unbound ``Form``.
+
+To specify dynamic initial data, see the :attr:`Form.initial` parameter.
+
+The use-case for this is when you want to display an "empty" form in which a
+field is initialized to a particular value. For example::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField(initial='Your name')
+    ...     url = forms.URLField(initial='http://')
+    ...     comment = forms.CharField()
+    >>> f = CommentForm(auto_id=False)
+    >>> print f
+    <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
+    <tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
+
+You may be thinking, why not just pass a dictionary of the initial values as
+data when displaying the form? Well, if you do that, you'll trigger validation,
+and the HTML output will include any validation errors::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField()
+    ...     url = forms.URLField()
+    ...     comment = forms.CharField()
+    >>> default_data = {'name': 'Your name', 'url': 'http://'}
+    >>> f = CommentForm(default_data, auto_id=False)
+    >>> print f
+    <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
+    <tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr>
+    <tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr>
+
+This is why ``initial`` values are only displayed for unbound forms. For bound
+forms, the HTML output will use the bound data.
+
+Also note that ``initial`` values are *not* used as "fallback" data in
+validation if a particular field's value is not given. ``initial`` values are
+*only* intended for initial form display::
+
+    >>> class CommentForm(forms.Form):
+    ...     name = forms.CharField(initial='Your name')
+    ...     url = forms.URLField(initial='http://')
+    ...     comment = forms.CharField()
+    >>> data = {'name': '', 'url': '', 'comment': 'Foo'}
+    >>> f = CommentForm(data)
+    >>> f.is_valid()
+    False
+    # The form does *not* fall back to using the initial values.
+    >>> f.errors
+    {'url': [u'This field is required.'], 'name': [u'This field is required.']}
+
+Instead of a constant, you can also pass any callable::
+
+    >>> import datetime
+    >>> class DateForm(forms.Form):
+    ...     day = forms.DateField(initial=datetime.date.today)
+    >>> print DateForm()
+    <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr>
+
+The callable will be evaluated only when the unbound form is displayed, not when it is defined.
+
+``widget``
+~~~~~~~~~~
+
+.. attribute:: Field.widget
+
+The ``widget`` argument lets you specify a ``Widget`` class to use when
+rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information.
+
+``help_text``
+~~~~~~~~~~~~~
+
+.. attribute:: Field.help_text
+
+The ``help_text`` argument lets you specify descriptive text for this
+``Field``. If you provide ``help_text``, it will be displayed next to the
+``Field`` when the ``Field`` is rendered by one of the convenience ``Form``
+methods (e.g., ``as_ul()``).
+
+Here's a full example ``Form`` that implements ``help_text`` for two of its
+fields. We've specified ``auto_id=False`` to simplify the output::
+
+    >>> class HelpTextContactForm(forms.Form):
+    ...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
+    ...     message = forms.CharField()
+    ...     sender = forms.EmailField(help_text='A valid e-mail address, please.')
+    ...     cc_myself = forms.BooleanField(required=False)
+    >>> f = HelpTextContactForm(auto_id=False)
+    >>> print f.as_table()
+    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
+    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
+    <tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr>
+    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
+    >>> print f.as_ul()
+    <li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li>
+    <li>Message: <input type="text" name="message" /></li>
+    <li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
+    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
+    >>> print f.as_p()
+    <p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
+    <p>Message: <input type="text" name="message" /></p>
+    <p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
+    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
+
+``error_messages``
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. attribute:: Field.error_messages
+
+The ``error_messages`` argument lets you override the default messages that the
+field will raise. Pass in a dictionary with keys matching the error messages you
+want to override. For example, here is the default error message::
+
+    >>> generic = forms.CharField()
+    >>> generic.clean('')
+    Traceback (most recent call last):
+      ...
+    ValidationError: [u'This field is required.']
+
+And here is a custom error message::
+
+    >>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
+    >>> name.clean('')
+    Traceback (most recent call last):
+      ...
+    ValidationError: [u'Please enter your name']
+
+In the `built-in Field classes`_ section below, each ``Field`` defines the
+error message keys it uses.
+
+``validators``
+~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+.. attribute:: Field.validators
+
+The ``validators`` argument lets you provide a list of validation functions
+for this field.
+
+See the :doc:`validators documentation </ref/validators>` for more information.
+
+``localize``
+~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+.. attribute:: Field.localize
+
+The ``localize`` argument enables the localization of form data, input as well
+as the rendered output.
+
+See the :ref:`format localization <format-localization>` documentation for
+more information.
+
+
+Built-in ``Field`` classes
+--------------------------
+
+Naturally, the ``forms`` library comes with a set of ``Field`` classes that
+represent common validation needs. This section documents each built-in field.
+
+For each field, we describe the default widget used if you don't specify
+``widget``. We also specify the value returned when you provide an empty value
+(see the section on ``required`` above to understand what that means).
+
+``BooleanField``
+~~~~~~~~~~~~~~~~
+
+.. class:: BooleanField(**kwargs)
+
+    * Default widget: ``CheckboxInput``
+    * Empty value: ``False``
+    * Normalizes to: A Python ``True`` or ``False`` value.
+    * Validates that the value is ``True`` (e.g. the check box is checked) if
+      the field has ``required=True``.
+    * Error message keys: ``required``
+
+.. versionchanged:: 1.0
+   The empty value for a ``CheckboxInput`` (and hence the standard
+   ``BooleanField``) has changed to return ``False`` instead of ``None`` in
+   the Django 1.0.
+
+.. note::
+
+    Since all ``Field`` subclasses have ``required=True`` by default, the
+    validation condition here is important. If you want to include a boolean
+    in your form that can be either ``True`` or ``False`` (e.g. a checked or
+    unchecked checkbox), you must remember to pass in ``required=False`` when
+    creating the ``BooleanField``.
+
+``CharField``
+~~~~~~~~~~~~~
+
+.. class:: CharField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates ``max_length`` or ``min_length``, if they are provided.
+      Otherwise, all inputs are valid.
+    * Error message keys: ``required``, ``max_length``, ``min_length``
+
+Has two optional arguments for validation:
+
+.. attribute:: CharField.max_length
+.. attribute:: CharField.min_length
+
+    If provided, these arguments ensure that the string is at most or at least
+    the given length.
+
+``ChoiceField``
+~~~~~~~~~~~~~~~
+
+.. class:: ChoiceField(**kwargs)
+
+    * Default widget: ``Select``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value exists in the list of choices.
+    * Error message keys: ``required``, ``invalid_choice``
+
+Takes one extra required argument:
+
+.. attribute:: ChoiceField.choices
+
+    An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
+    field. This argument accepts the same formats as the ``choices`` argument
+    to a model field. See the :ref:`model field reference documentation on
+    choices <field-choices>` for more details.
+
+``TypedChoiceField``
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: TypedChoiceField(**kwargs)
+
+Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes an
+extra ``coerce`` argument.
+
+    * Default widget: ``Select``
+    * Empty value: Whatever you've given as ``empty_value``
+    * Normalizes to: the value returned by the ``coerce`` argument.
+    * Validates that the given value exists in the list of choices.
+    * Error message keys: ``required``, ``invalid_choice``
+
+Takes extra arguments:
+
+.. attribute:: TypedChoiceField.coerce
+
+    A function that takes one argument and returns a coerced value. Examples
+    include the built-in ``int``, ``float``, ``bool`` and other types. Defaults
+    to an identity function.
+
+.. attribute:: TypedChoiceField.empty_value
+
+    The value to use to represent "empty." Defaults to the empty string;
+    ``None`` is another common choice here.
+
+``DateField``
+~~~~~~~~~~~~~
+
+.. class:: DateField(**kwargs)
+
+    * Default widget: ``DateInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``datetime.date`` object.
+    * Validates that the given value is either a ``datetime.date``,
+      ``datetime.datetime`` or string formatted in a particular date format.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one optional argument:
+
+.. attribute:: DateField.input_formats
+
+    A list of formats used to attempt to convert a string to a valid
+    ``datetime.date`` object.
+
+If no ``input_formats`` argument is provided, the default input formats are::
+
+    '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
+    '%b %d %Y', '%b %d, %Y',            # 'Oct 25 2006', 'Oct 25, 2006'
+    '%d %b %Y', '%d %b, %Y',            # '25 Oct 2006', '25 Oct, 2006'
+    '%B %d %Y', '%B %d, %Y',            # 'October 25 2006', 'October 25, 2006'
+    '%d %B %Y', '%d %B, %Y',            # '25 October 2006', '25 October, 2006'
+
+.. versionchanged:: 1.1
+   The ``DateField`` previously used a ``TextInput`` widget by default. It now
+   uses a ``DateInput`` widget.
+
+``DateTimeField``
+~~~~~~~~~~~~~~~~~
+
+.. class:: DateTimeField(**kwargs)
+
+    * Default widget: ``DateTimeInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``datetime.datetime`` object.
+    * Validates that the given value is either a ``datetime.datetime``,
+      ``datetime.date`` or string formatted in a particular datetime format.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one optional argument:
+
+.. attribute:: DateTimeField.input_formats
+
+    A list of formats used to attempt to convert a string to a valid
+    ``datetime.datetime`` object.
+
+If no ``input_formats`` argument is provided, the default input formats are::
+
+    '%Y-%m-%d %H:%M:%S',     # '2006-10-25 14:30:59'
+    '%Y-%m-%d %H:%M',        # '2006-10-25 14:30'
+    '%Y-%m-%d',              # '2006-10-25'
+    '%m/%d/%Y %H:%M:%S',     # '10/25/2006 14:30:59'
+    '%m/%d/%Y %H:%M',        # '10/25/2006 14:30'
+    '%m/%d/%Y',              # '10/25/2006'
+    '%m/%d/%y %H:%M:%S',     # '10/25/06 14:30:59'
+    '%m/%d/%y %H:%M',        # '10/25/06 14:30'
+    '%m/%d/%y',              # '10/25/06'
+
+.. versionchanged:: 1.0
+   The ``DateTimeField`` used to use a ``TextInput`` widget by default. This has now changed.
+
+``DecimalField``
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. class:: DecimalField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``decimal``.
+    * Validates that the given value is a decimal. Leading and trailing
+      whitespace is ignored.
+    * Error message keys: ``required``, ``invalid``, ``max_value``,
+      ``min_value``, ``max_digits``, ``max_decimal_places``,
+      ``max_whole_digits``
+
+Takes four optional arguments:
+
+.. attribute:: DecimalField.max_value
+.. attribute:: DecimalField.min_value
+
+    These attributes define the limits for the fields value.
+
+.. attribute:: DecimalField.max_digits
+
+    The maximum number of digits (those before the decimal point plus those
+    after the decimal point, with leading zeros stripped) permitted in the
+    value.
+
+.. attribute:: DecimalField.decimal_places
+
+    The maximum number of decimal places permitted.
+
+``EmailField``
+~~~~~~~~~~~~~~
+
+.. class:: EmailField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value is a valid e-mail address, using a
+      moderately complex regular expression.
+    * Error message keys: ``required``, ``invalid``
+
+Has two optional arguments for validation, ``max_length`` and ``min_length``.
+If provided, these arguments ensure that the string is at most or at least the
+given length.
+
+.. versionchanged:: 1.2
+   The EmailField previously did not recognize e-mail addresses as valid that
+   contained an IDN (Internationalized Domain Name; a domain containing
+   unicode characters) domain part. This has now been corrected.
+
+``FileField``
+~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. class:: FileField(**kwargs)
+
+    * Default widget: ``FileInput``
+    * Empty value: ``None``
+    * Normalizes to: An ``UploadedFile`` object that wraps the file content
+      and file name into a single object.
+    * Validates that non-empty file data has been bound to the form.
+    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``
+
+To learn more about the ``UploadedFile`` object, see the :doc:`file uploads
+documentation </topics/http/file-uploads>`.
+
+When you use a ``FileField`` in a form, you must also remember to
+:ref:`bind the file data to the form <binding-uploaded-files>`.
+
+``FilePathField``
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. class:: FilePathField(**kwargs)
+
+    * Default widget: ``Select``
+    * Empty value: ``None``
+    * Normalizes to: A unicode object
+    * Validates that the selected choice exists in the list of choices.
+    * Error message keys: ``required``, ``invalid_choice``
+
+The field allows choosing from files inside a certain directory. It takes three
+extra arguments; only ``path`` is required:
+
+.. attribute:: FilePathField.path
+
+    The absolute path to the directory whose contents you want listed. This
+    directory must exist.
+
+.. attribute:: FilePathField.recursive
+
+    If ``False`` (the default) only the direct contents of ``path`` will be
+    offered as choices. If ``True``, the directory will be descended into
+    recursively and all descendants will be listed as choices.
+
+.. attribute:: FilePathField.match
+
+    A regular expression pattern; only files with names matching this expression
+    will be allowed as choices.
+
+``FloatField``
+~~~~~~~~~~~~~~
+
+    * Default widget: ``TextInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python float.
+    * Validates that the given value is an float. Leading and trailing
+      whitespace is allowed, as in Python's ``float()`` function.
+    * Error message keys: ``required``, ``invalid``, ``max_value``,
+      ``min_value``
+
+Takes two optional arguments for validation, ``max_value`` and ``min_value``.
+These control the range of values permitted in the field.
+
+``ImageField``
+~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. class:: ImageField(**kwargs)
+
+    * Default widget: ``FileInput``
+    * Empty value: ``None``
+    * Normalizes to: An ``UploadedFile`` object that wraps the file content
+      and file name into a single object.
+    * Validates that file data has been bound to the form, and that the
+      file is of an image format understood by PIL.
+    * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
+      ``invalid_image``
+
+Using an ImageField requires that the `Python Imaging Library`_ is installed.
+
+When you use an ``ImageField`` on a form, you must also remember to
+:ref:`bind the file data to the form <binding-uploaded-files>`.
+
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
+``IntegerField``
+~~~~~~~~~~~~~~~~
+
+.. class:: IntegerField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python integer or long integer.
+    * Validates that the given value is an integer. Leading and trailing
+      whitespace is allowed, as in Python's ``int()`` function.
+    * Error message keys: ``required``, ``invalid``, ``max_value``,
+      ``min_value``
+
+Takes two optional arguments for validation:
+
+.. attribute:: IntegerField.max_value
+.. attribute:: IntegerField.min_value
+
+    These control the range of values permitted in the field.
+
+``IPAddressField``
+~~~~~~~~~~~~~~~~~~
+
+.. class:: IPAddressField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value is a valid IPv4 address, using a regular
+      expression.
+    * Error message keys: ``required``, ``invalid``
+
+``MultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultipleChoiceField(**kwargs)
+
+    * Default widget: ``SelectMultiple``
+    * Empty value: ``[]`` (an empty list)
+    * Normalizes to: A list of Unicode objects.
+    * Validates that every value in the given list of values exists in the list
+      of choices.
+    * Error message keys: ``required``, ``invalid_choice``, ``invalid_list``
+
+Takes one extra argument, ``choices``, as for ``ChoiceField``.
+
+``NullBooleanField``
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: NullBooleanField(**kwargs)
+
+    * Default widget: ``NullBooleanSelect``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``True``, ``False`` or ``None`` value.
+    * Validates nothing (i.e., it never raises a ``ValidationError``).
+
+``RegexField``
+~~~~~~~~~~~~~~
+
+.. class:: RegexField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value matches against a certain regular
+      expression.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one required argument:
+
+.. attribute:: RegexField.regex
+
+    A regular expression specified either as a string or a compiled regular
+    expression object.
+
+Also takes ``max_length`` and ``min_length``, which work just as they do for
+``CharField``.
+
+The optional argument ``error_message`` is also accepted for backwards
+compatibility. The preferred way to provide an error message is to use the
+``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key
+and the error message as the value.
+
+``SlugField``
+~~~~~~~~~~~~~
+
+.. class:: SlugField(**kwargs)
+
+   * Default widget: ``TextInput``
+   * Empty value: ``''`` (an empty string)
+   * Normalizes to: A Unicode object.
+   * Validates that the given value contains only letters, numbers,
+     underscores, and hyphens.
+   * Error messages: ``required``, ``invalid``
+
+This field is intended for use in representing a model
+:class:`~django.db.models.SlugField` in forms.
+
+``TimeField``
+~~~~~~~~~~~~~
+
+.. class:: TimeField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``datetime.time`` object.
+    * Validates that the given value is either a ``datetime.time`` or string
+      formatted in a particular time format.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one optional argument:
+
+.. attribute:: TimeField.input_formats
+
+    A list of formats used to attempt to convert a string to a valid
+    ``datetime.time`` object.
+
+If no ``input_formats`` argument is provided, the default input formats are::
+
+    '%H:%M:%S',     # '14:30:59'
+    '%H:%M',        # '14:30'
+
+``URLField``
+~~~~~~~~~~~~
+
+.. class:: URLField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value is a valid URL.
+    * Error message keys: ``required``, ``invalid``, ``invalid_link``
+
+Takes the following optional arguments:
+
+.. attribute:: URLField.max_length
+.. attribute:: URLField.min_length
+
+    Same as ``CharField.max_length`` and ``CharField.min_length``.
+
+.. attribute:: URLField.verify_exists
+
+    If ``True``, the validator will attempt to load the given URL, raising
+    ``ValidationError`` if the page gives a 404. Defaults to ``False``.
+
+.. attribute:: URLField.validator_user_agent
+
+    String used as the user-agent used when checking for a URL's existence.
+    Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting.
+
+.. versionchanged:: 1.2
+   The URLField previously did not recognize URLs as valid that contained an IDN
+   (Internationalized Domain Name; a domain name containing unicode characters)
+   domain name. This has now been corrected.
+
+
+Slightly complex built-in ``Field`` classes
+-------------------------------------------
+
+``ComboField``
+~~~~~~~~~~~~~~
+
+.. class:: ComboField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Unicode object.
+    * Validates that the given value against each of the fields specified
+      as an argument to the ``ComboField``.
+    * Error message keys: ``required``, ``invalid``
+
+Takes one extra required argument:
+
+.. attribute:: ComboField.fields
+
+    The list of fields that should be used to validate the field's value (in
+    the order in which they are provided).
+
+        >>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
+        >>> f.clean('test@example.com')
+        u'test@example.com'
+        >>> f.clean('longemailaddress@example.com')
+        Traceback (most recent call last):
+        ...
+        ValidationError: [u'Ensure this value has at most 20 characters (it has 28).']
+
+``MultiValueField``
+~~~~~~~~~~~~~~~~~~~
+
+.. class:: MultiValueField(**kwargs)
+
+    * Default widget: ``TextInput``
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: the type returned by the ``compress`` method of the subclass.
+    * Validates that the given value against each of the fields specified
+      as an argument to the ``MultiValueField``.
+    * Error message keys: ``required``, ``invalid``
+
+    This abstract field (must be subclassed) aggregates the logic of multiple
+    fields. Subclasses should not have to implement clean(). Instead, they must
+    implement compress(), which takes a list of valid values and returns a
+    "compressed" version of those values -- a single value.  For example,
+    :class:`SplitDateTimeField` is a subclass which combines a time field and
+    a date field into a datetime object.
+
+Takes one extra required argument:
+
+.. attribute:: MultiValueField.fields
+
+    A list of fields which are cleaned into a single field. Each value in
+    ``clean`` is cleaned by the corresponding field in ``fields`` -- the first
+    value is cleaned by the first field, the second value is cleaned by
+    the second field, etc.  Once all fields are cleaned, the list of clean
+    values is "compressed" into a single value.
+
+``SplitDateTimeField``
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: SplitDateTimeField(**kwargs)
+
+    * Default widget: ``SplitDateTimeWidget``
+    * Empty value: ``None``
+    * Normalizes to: A Python ``datetime.datetime`` object.
+    * Validates that the given value is a ``datetime.datetime`` or string
+      formatted in a particular datetime format.
+    * Error message keys: ``required``, ``invalid``
+
+Takes two optional arguments:
+
+.. attribute:: SplitDateTimeField.input_date_formats
+
+    A list of formats used to attempt to convert a string to a valid
+    ``datetime.date`` object.
+
+If no ``input_date_formats`` argument is provided, the default input formats
+for ``DateField`` are used.
+
+.. attribute:: SplitDateTimeField.input_time_formats
+
+    A list of formats used to attempt to convert a string to a valid
+    ``datetime.time`` object.
+
+If no ``input_time_formats`` argument is provided, the default input formats
+for ``TimeField`` are used.
+
+.. versionchanged:: 1.1
+   The ``SplitDateTimeField`` previously used two ``TextInput`` widgets by
+   default. The ``input_date_formats`` and ``input_time_formats`` arguments
+   are also new.
+
+Fields which handle relationships
+---------------------------------
+
+Two fields are available for representing relationships between
+models: :class:`ModelChoiceField` and
+:class:`ModelMultipleChoiceField`.  Both of these fields require a
+single ``queryset`` parameter that is used to create the choices for
+the field.  Upon form validation, these fields will place either one
+model object (in the case of ``ModelChoiceField``) or multiple model
+objects (in the case of ``ModelMultipleChoiceField``) into the
+``cleaned_data`` dictionary of the form.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
+
+.. class:: ModelChoiceField(**kwargs)
+
+    * Default widget: ``Select``
+    * Empty value: ``None``
+    * Normalizes to: A model instance.
+    * Validates that the given id exists in the queryset.
+    * Error message keys: ``required``, ``invalid_choice``
+
+Allows the selection of a single model object, suitable for
+representing a foreign key.  A single argument is required:
+
+.. attribute:: ModelChoiceField.queryset
+
+    A ``QuerySet`` of model objects from which the choices for the
+    field will be derived, and which will be used to validate the
+    user's selection.
+
+``ModelChoiceField`` also takes one optional argument:
+
+.. attribute:: ModelChoiceField.empty_label
+
+    By default the ``<select>`` widget used by ``ModelChoiceField`` will have a
+    an empty choice at the top of the list. You can change the text of this
+    label (which is ``"---------"`` by default) with the ``empty_label``
+    attribute, or you can disable the empty label entirely by setting
+    ``empty_label`` to ``None``::
+
+        # A custom empty label
+        field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
+
+        # No empty label
+        field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+
+    Note that if a ``ModelChoiceField`` is required and has a default
+    initial value, no empty choice is created (regardless of the value
+    of ``empty_label``).
+
+The ``__unicode__`` method of the model will be called to generate
+string representations of the objects for use in the field's choices;
+to provide customized representations, subclass ``ModelChoiceField``
+and override ``label_from_instance``. This method will receive a model
+object, and should return a string suitable for representing it. For
+example::
+
+    class MyModelChoiceField(ModelChoiceField):
+        def label_from_instance(self, obj):
+            return "My Object #%i" % obj.id
+
+``ModelMultipleChoiceField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: ModelMultipleChoiceField(**kwargs)
+
+    * Default widget: ``SelectMultiple``
+    * Empty value: ``[]`` (an empty list)
+    * Normalizes to: A list of model instances.
+    * Validates that every id in the given list of values exists in the
+      queryset.
+    * Error message keys: ``required``, ``list``, ``invalid_choice``,
+      ``invalid_pk_value``
+
+Allows the selection of one or more model objects, suitable for
+representing a many-to-many relation. As with :class:`ModelChoiceField`,
+you can use ``label_from_instance`` to customize the object
+representations, and ``queryset`` is a required parameter:
+
+.. attribute:: ModelMultipleChoiceField.queryset
+
+    A ``QuerySet`` of model objects from which the choices for the
+    field will be derived, and which will be used to validate the
+    user's selection.
+
+Creating custom fields
+----------------------
+
+If the built-in ``Field`` classes don't meet your needs, you can easily create
+custom ``Field`` classes. To do this, just create a subclass of
+``django.forms.Field``. Its only requirements are that it implement a
+``clean()`` method and that its ``__init__()`` method accept the core arguments
+mentioned above (``required``, ``label``, ``initial``, ``widget``,
+``help_text``).
diff --git a/parts/django/docs/ref/forms/index.txt b/parts/django/docs/ref/forms/index.txt
new file mode 100644
index 0000000..866afed
--- /dev/null
+++ b/parts/django/docs/ref/forms/index.txt
@@ -0,0 +1,13 @@
+=====
+Forms
+=====
+
+Detailed form API reference. For introductory material, see :doc:`/topics/forms/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   fields
+   widgets
+   validation
diff --git a/parts/django/docs/ref/forms/validation.txt b/parts/django/docs/ref/forms/validation.txt
new file mode 100644
index 0000000..1c047f2
--- /dev/null
+++ b/parts/django/docs/ref/forms/validation.txt
@@ -0,0 +1,366 @@
+Form and field validation
+=========================
+
+.. versionchanged:: 1.2
+
+Form validation happens when the data is cleaned. If you want to customize
+this process, there are various places you can change, each one serving a
+different purpose. Three types of cleaning methods are run during form
+processing. These are normally executed when you call the ``is_valid()``
+method on a form. There are other things that can trigger cleaning and
+validation (accessing the ``errors`` attribute or calling ``full_clean()``
+directly), but normally they won't be needed.
+
+In general, any cleaning method can raise ``ValidationError`` if there is a
+problem with the data it is processing, passing the relevant error message to
+the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the
+method should return the cleaned (normalized) data as a Python object.
+
+If you detect multiple errors during a cleaning method and wish to signal all
+of them to the form submitter, it is possible to pass a list of errors to the
+``ValidationError`` constructor.
+
+Most validation can be done using `validators`_ - simple helpers that can be
+reused easily. Validators are simple functions (or callables) that take a single
+argument and raise ``ValidationError`` on invalid input. Validators are run
+after the field's ``to_python`` and ``validate`` methods have been called.
+
+Validation of a Form is split into several steps, which can be customized or
+overridden:
+
+    * The ``to_python()`` method on a Field is the first step in every
+      validation. It coerces the value to correct datatype and raises
+      ``ValidationError`` if that is not possible. This method accepts the raw
+      value from the widget and returns the converted value. For example, a
+      FloatField will turn the data into a Python ``float`` or raise a
+      ``ValidationError``.
+
+    * The ``validate()`` method on a Field handles field-specific validation
+      that is not suitable for a validator, It takes a value that has been
+      coerced to correct datatype and raises ``ValidationError`` on any error.
+      This method does not return anything and shouldn't alter the value. You
+      should override it to handle validation logic that you can't or don't
+      want to put in a validator.
+
+    * The ``run_validators()`` method on a Field runs all of the field's
+      validators and aggregates all the errors into a single
+      ``ValidationError``. You shouldn't need to override this method.
+
+    * The ``clean()`` method on a Field subclass. This is responsible for
+      running ``to_python``, ``validate`` and ``run_validators`` in the correct
+      order and propagating their errors. If, at any time, any of the methods
+      raise ``ValidationError``, the validation stops and that error is raised.
+      This method returns the clean data, which is then inserted into the
+      ``cleaned_data`` dictionary of the form.
+
+    * The ``clean_<fieldname>()`` method in a form subclass -- where
+      ``<fieldname>`` is replaced with the name of the form field attribute.
+      This method does any cleaning that is specific to that particular
+      attribute, unrelated to the type of field that it is. This method is not
+      passed any parameters. You will need to look up the value of the field
+      in ``self.cleaned_data`` and remember that it will be a Python object
+      at this point, not the original string submitted in the form (it will be
+      in ``cleaned_data`` because the general field ``clean()`` method, above,
+      has already cleaned the data once).
+
+      For example, if you wanted to validate that the contents of a
+      ``CharField`` called ``serialnumber`` was unique,
+      ``clean_serialnumber()`` would be the right place to do this. You don't
+      need a specific field (it's just a ``CharField``), but you want a
+      formfield-specific piece of validation and, possibly,
+      cleaning/normalizing the data.
+
+      Just like the general field ``clean()`` method, above, this method
+      should return the cleaned data, regardless of whether it changed
+      anything or not.
+
+    * The Form subclass's ``clean()`` method. This method can perform
+      any validation that requires access to multiple fields from the form at
+      once. This is where you might put in things to check that if field ``A``
+      is supplied, field ``B`` must contain a valid e-mail address and the
+      like. The data that this method returns is the final ``cleaned_data``
+      attribute for the form, so don't forget to return the full list of
+      cleaned data if you override this method (by default, ``Form.clean()``
+      just returns ``self.cleaned_data``).
+
+      Note that any errors raised by your ``Form.clean()`` override will not
+      be associated with any field in particular. They go into a special
+      "field" (called ``__all__``), which you can access via the
+      ``non_field_errors()`` method if you need to. If you want to attach
+      errors to a specific field in the form, you will need to access the
+      ``_errors`` attribute on the form, which is `described later`_.
+
+      Also note that there are special considerations when overriding
+      the ``clean()`` method of a ``ModelForm`` subclass. (see the
+      :ref:`ModelForm documentation
+      <overriding-modelform-clean-method>` for more information)
+
+These methods are run in the order given above, one field at a time.  That is,
+for each field in the form (in the order they are declared in the form
+definition), the ``Field.clean()`` method (or its override) is run, then
+``clean_<fieldname>()``. Finally, once those two methods are run for every
+field, the ``Form.clean()`` method, or its override, is executed.
+
+Examples of each of these methods are provided below.
+
+As mentioned, any of these methods can raise a ``ValidationError``. For any
+field, if the ``Field.clean()`` method raises a ``ValidationError``, any
+field-specific cleaning method is not called. However, the cleaning methods
+for all remaining fields are still executed.
+
+The ``clean()`` method for the ``Form`` class or subclass is always run. If
+that method raises a ``ValidationError``, ``cleaned_data`` will be an empty
+dictionary.
+
+The previous paragraph means that if you are overriding ``Form.clean()``, you
+should iterate through ``self.cleaned_data.items()``, possibly considering the
+``_errors`` dictionary attribute on the form as well. In this way, you will
+already know which fields have passed their individual validation requirements.
+
+.. _described later:
+
+Form subclasses and modifying field errors
+------------------------------------------
+
+Sometimes, in a form's ``clean()`` method, you will want to add an error
+message to a particular field in the form. This won't always be appropriate
+and the more typical situation is to raise a ``ValidationError`` from
+``Form.clean()``, which is turned into a form-wide error that is available
+through the ``Form.non_field_errors()`` method.
+
+When you really do need to attach the error to a particular field, you should
+store (or amend) a key in the ``Form._errors`` attribute. This attribute is an
+instance of a ``django.forms.util.ErrorDict`` class. Essentially, though, it's
+just a dictionary. There is a key in the dictionary for each field in the form
+that has an error. Each value in the dictionary is a
+``django.forms.util.ErrorList`` instance, which is a list that knows how to
+display itself in different ways. So you can treat ``_errors`` as a dictionary
+mapping field names to lists.
+
+If you want to add a new error to a particular field, you should check whether
+the key already exists in ``self._errors`` or not. If not, create a new entry
+for the given key, holding an empty ``ErrorList`` instance. In either case,
+you can then append your error message to the list for the field name in
+question and it will be displayed when the form is displayed.
+
+There is an example of modifying ``self._errors`` in the following section.
+
+.. admonition:: What's in a name?
+
+    You may be wondering why is this attribute called ``_errors`` and not
+    ``errors``. Normal Python practice is to prefix a name with an underscore
+    if it's not for external usage. In this case, you are subclassing the
+    ``Form`` class, so you are essentially writing new internals. In effect,
+    you are given permission to access some of the internals of ``Form``.
+
+    Of course, any code outside your form should never access ``_errors``
+    directly. The data is available to external code through the ``errors``
+    property, which populates ``_errors`` before returning it).
+
+    Another reason is purely historical: the attribute has been called
+    ``_errors`` since the early days of the forms module and changing it now
+    (particularly since ``errors`` is used for the read-only property name)
+    would be inconvenient for a number of reasons. You can use whichever
+    explanation makes you feel more comfortable. The result is the same.
+
+Using validation in practice
+----------------------------
+
+The previous sections explained how validation works in general for forms.
+Since it can sometimes be easier to put things into place by seeing each
+feature in use, here are a series of small examples that use each of the
+previous features.
+
+.. _validators:
+
+Using validators
+~~~~~~~~~~~~~~~~
+.. versionadded:: 1.2
+
+Django's form (and model) fields support use of simple utility functions and
+classes known as validators. These can be passed to a field's constructor, via
+the field's ``validators`` argument, or defined on the Field class itself with
+the ``default_validators`` attribute.
+
+Simple validators can be used to validate values inside the field, let's have
+a look at Django's ``EmailField``::
+
+    class EmailField(CharField):
+        default_error_messages = {
+            'invalid': _(u'Enter a valid e-mail address.'),
+        }
+        default_validators = [validators.validate_email]
+
+As you can see, ``EmailField`` is just a ``CharField`` with customized error
+message and a validator that validates e-mail addresses. This can also be done
+on field definition so::
+
+    email = forms.EmailField()
+
+is equivalent to::
+
+    email = forms.CharField(validators=[validators.validate_email],
+            error_messages={'invalid': _(u'Enter a valid e-mail address.')})
+
+
+Form field default cleaning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Let's firstly create a custom form field that validates its input is a string
+containing comma-separated e-mail addresses. The full class looks like this::
+
+    from django import forms
+    from django.core.validators import validate_email
+
+    class MultiEmailField(forms.Field):
+        def to_python(self, value):
+            "Normalize data to a list of strings."
+
+            # Return an empty list if no input was given.
+            if not value:
+                return []
+            return value.split(',')
+
+        def validate(self, value):
+            "Check if value consists only of valid emails."
+
+            # Use the parent's handling of required fields, etc.
+            super(MultiEmailField, self).validate(value)
+
+            for email in value:
+                validate_email(email)
+
+Every form that uses this field will have these methods run before anything
+else can be done with the field's data. This is cleaning that is specific to
+this type of field, regardless of how it is subsequently used.
+
+Let's create a simple ``ContactForm`` to demonstrate how you'd use this
+field::
+
+    class ContactForm(forms.Form):
+        subject = forms.CharField(max_length=100)
+        message = forms.CharField()
+        sender = forms.EmailField()
+        recipients = MultiEmailField()
+        cc_myself = forms.BooleanField(required=False)
+
+Simply use ``MultiEmailField`` like any other form field. When the
+``is_valid()`` method is called on the form, the ``MultiEmailField.clean()``
+method will be run as part of the cleaning process and it will, in turn, call
+the custom ``to_python()`` and ``validate()`` methods.
+
+Cleaning a specific field attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Continuing on from the previous example, suppose that in our ``ContactForm``,
+we want to make sure that the ``recipients`` field always contains the address
+``"fred@example.com"``. This is validation that is specific to our form, so we
+don't want to put it into the general ``MultiEmailField`` class. Instead, we
+write a cleaning method that operates on the ``recipients`` field, like so::
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean_recipients(self):
+            data = self.cleaned_data['recipients']
+            if "fred@example.com" not in data:
+                raise forms.ValidationError("You have forgotten about Fred!")
+
+            # Always return the cleaned data, whether you have changed it or
+            # not.
+            return data
+
+Cleaning and validating fields that depend on each other
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose we add another requirement to our contact form: if the ``cc_myself``
+field is ``True``, the ``subject`` must contain the word ``"help"``. We are
+performing validation on more than one field at a time, so the form's
+``clean()`` method is a good spot to do this. Notice that we are talking about
+the ``clean()`` method on the form here, whereas earlier we were writing a
+``clean()`` method on a field. It's important to keep the field and form
+difference clear when working out where to validate things. Fields are single
+data points, forms are a collection of fields.
+
+By the time the form's ``clean()`` method is called, all the individual field
+clean methods will have been run (the previous two sections), so
+``self.cleaned_data`` will be populated with any data that has survived so
+far. So you also need to remember to allow for the fact that the fields you
+are wanting to validate might not have survived the initial individual field
+checks.
+
+There are two way to report any errors from this step. Probably the most
+common method is to display the error at the top of the form. To create such
+an error, you can raise a ``ValidationError`` from the ``clean()`` method. For
+example::
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean(self):
+            cleaned_data = self.cleaned_data
+            cc_myself = cleaned_data.get("cc_myself")
+            subject = cleaned_data.get("subject")
+
+            if cc_myself and subject:
+                # Only do something if both fields are valid so far.
+                if "help" not in subject:
+                    raise forms.ValidationError("Did not send for 'help' in "
+                            "the subject despite CC'ing yourself.")
+
+            # Always return the full collection of cleaned data.
+            return cleaned_data
+
+In this code, if the validation error is raised, the form will display an
+error message at the top of the form (normally) describing the problem.
+
+The second approach might involve assigning the error message to one of the
+fields. In this case, let's assign an error message to both the "subject" and
+"cc_myself" rows in the form display. Be careful when doing this in practice,
+since it can lead to confusing form output. We're showing what is possible
+here and leaving it up to you and your designers to work out what works
+effectively in your particular situation. Our new code (replacing the previous
+sample) looks like this::
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean(self):
+            cleaned_data = self.cleaned_data
+            cc_myself = cleaned_data.get("cc_myself")
+            subject = cleaned_data.get("subject")
+
+            if cc_myself and subject and "help" not in subject:
+                # We know these are not in self._errors now (see discussion
+                # below).
+                msg = u"Must put 'help' in subject when cc'ing yourself."
+                self._errors["cc_myself"] = self.error_class([msg])
+                self._errors["subject"] = self.error_class([msg])
+
+                # These fields are no longer valid. Remove them from the
+                # cleaned data.
+                del cleaned_data["cc_myself"]
+                del cleaned_data["subject"]
+
+            # Always return the full collection of cleaned data.
+            return cleaned_data
+
+As you can see, this approach requires a bit more effort, not withstanding the
+extra design effort to create a sensible form display. The details are worth
+noting, however. Firstly, earlier we mentioned that you might need to check if
+the field name keys already exist in the ``_errors`` dictionary. In this case,
+since we know the fields exist in ``self.cleaned_data``, they must have been
+valid when cleaned as individual fields, so there will be no corresponding
+entries in ``_errors``.
+
+Secondly, once we have decided that the combined data in the two fields we are
+considering aren't valid, we must remember to remove them from the
+``cleaned_data``.
+
+In fact, Django will currently completely wipe out the ``cleaned_data``
+dictionary if there are any errors in the form. However, this behaviour may
+change in the future, so it's not a bad idea to clean up after yourself in the
+first place.
diff --git a/parts/django/docs/ref/forms/widgets.txt b/parts/django/docs/ref/forms/widgets.txt
new file mode 100644
index 0000000..9d78b84
--- /dev/null
+++ b/parts/django/docs/ref/forms/widgets.txt
@@ -0,0 +1,247 @@
+=======
+Widgets
+=======
+
+.. module:: django.forms.widgets
+   :synopsis: Django's built-in form widgets.
+   
+.. currentmodule:: django.forms
+
+A widget is Django's representation of a HTML input element. The widget
+handles the rendering of the HTML, and the extraction of data from a GET/POST
+dictionary that corresponds to the widget.
+
+Django provides a representation of all the basic HTML widgets, plus some
+commonly used groups of widgets:
+
+.. class:: TextInput
+
+    Text input: ``<input type='text' ...>``
+
+.. class:: PasswordInput
+
+    Password input: ``<input type='password' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: PasswordInput.render_value
+
+        Determines whether the widget will have a value filled in when the
+        form is re-displayed after a validation error (default is ``True``).
+
+.. class:: HiddenInput
+
+    Hidden input: ``<input type='hidden' ...>``
+
+.. class:: MultipleHiddenInput
+
+    Multiple ``<input type='hidden' ...>`` widgets.
+
+.. class:: FileInput
+
+    File upload input: ``<input type='file' ...>``
+
+.. class:: DateInput
+
+    .. versionadded:: 1.1
+
+    Date input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+    
+    .. attribute:: DateInput.format
+
+        The format in which this field's initial value will be displayed.
+
+    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
+
+.. class:: DateTimeInput
+
+    .. versionadded:: 1.0
+
+    Date/time input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+    
+    .. attribute:: DateTimeInput.format
+    
+        The format in which this field's initial value will be displayed.
+    
+    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
+    %H:%M:%S'``.
+
+.. class:: TimeInput
+
+    Time input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+    
+    .. attribute:: TimeInput.format
+    
+        The format in which this field's initial value will be displayed.
+    
+    If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
+
+    .. versionchanged:: 1.1
+       The ``format`` argument was not supported in Django 1.0.
+
+.. class:: Textarea
+
+    Text area: ``<textarea>...</textarea>``
+
+.. class:: CheckboxInput
+
+    Checkbox: ``<input type='checkbox' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: CheckboxInput.check_test
+     
+        A callable that takes the value of the CheckBoxInput 
+        and returns ``True`` if the checkbox should be checked for
+        that value. 
+
+.. class:: Select
+
+    Select widget: ``<select><option ...>...</select>``
+    
+    Requires that your field provides :attr:`~Field.choices`.
+
+.. class:: NullBooleanSelect
+
+    Select widget with options 'Unknown', 'Yes' and 'No'
+
+.. class:: SelectMultiple
+
+    Select widget allowing multiple selection: ``<select
+    multiple='multiple'>...</select>``
+
+    Requires that your field provides :attr:`~Field.choices`.
+
+.. class:: RadioSelect
+
+    A list of radio buttons:
+    
+    .. code-block:: html
+    
+        <ul>
+          <li><input type='radio' ...></li>
+          ...
+        </ul>
+        
+    Requires that your field provides :attr:`~Field.choices`.
+
+.. class:: CheckboxSelectMultiple
+
+    A list of checkboxes:
+    
+    .. code-block:: html
+    
+        <ul>
+          <li><input type='checkbox' ...></li>
+          ...
+        </ul>
+
+.. class:: MultiWidget
+
+    Wrapper around multiple other widgets
+
+.. class:: SplitDateTimeWidget
+
+    Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
+    for the time.
+
+    Takes two optional arguments, ``date_format`` and ``time_format``, which
+    work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
+    
+    .. versionchanged:: 1.1
+       The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0.
+
+.. class:: SelectDateWidget
+
+    Wrapper around three select widgets: one each for month, day, and year.
+    Note that this widget lives in a separate file from the standard widgets.
+
+    .. code-block:: python
+
+        from django.forms.extras.widgets import SelectDateWidget
+
+        date = forms.DateField(widget=SelectDateWidget())
+
+Specifying widgets
+------------------
+
+.. attribute:: Form.widget
+
+Whenever you specify a field on a form, Django will use a default widget
+that is appropriate to the type of data that is to be displayed. To find
+which widget is used on which field, see the documentation for the
+built-in Field classes.
+
+However, if you want to use a different widget for a field, you can -
+just use the 'widget' argument on the field definition. For example::
+
+    from django import forms
+
+    class CommentForm(forms.Form):
+        name = forms.CharField()
+        url = forms.URLField()
+        comment = forms.CharField(widget=forms.Textarea)
+
+This would specify a form with a comment that uses a larger Textarea widget,
+rather than the default TextInput widget.
+
+Customizing widget instances
+----------------------------
+
+When Django renders a widget as HTML, it only renders the bare minimum
+HTML - Django doesn't add a class definition, or any other widget-specific
+attributes. This means that all 'TextInput' widgets will appear the same
+on your Web page.
+
+If you want to make one widget look different to another, you need to
+specify additional attributes for each widget. When you specify a
+widget, you can provide a list of attributes that will be added to the
+rendered HTML for the widget.
+
+For example, take the following simple form::
+
+    class CommentForm(forms.Form):
+        name = forms.CharField()
+        url = forms.URLField()
+        comment = forms.CharField()
+
+This form will include three default TextInput widgets, with default rendering -
+no CSS class, no extra attributes. This means that the input boxes provided for
+each widget will be rendered exactly the same::
+
+    >>> f = CommentForm(auto_id=False)
+    >>> f.as_table()
+    <tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
+    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
+
+
+On a real Web page, you probably don't want every widget to look the same. You
+might want a larger input element for the comment, and you might want the 'name'
+widget to have some special CSS class. To do this, you use the ``attrs``
+argument when creating the widget:
+
+.. attribute:: Widget.attrs
+
+For example::
+
+    class CommentForm(forms.Form):
+        name = forms.CharField(
+                    widget=forms.TextInput(attrs={'class':'special'}))
+        url = forms.URLField()
+        comment = forms.CharField(
+                   widget=forms.TextInput(attrs={'size':'40'}))
+
+Django will then include the extra attributes in the rendered output::
+
+    >>> f = CommentForm(auto_id=False)
+    >>> f.as_table()
+    <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
+    <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
+    <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
diff --git a/parts/django/docs/ref/generic-views.txt b/parts/django/docs/ref/generic-views.txt
new file mode 100644
index 0000000..ea7fe2a
--- /dev/null
+++ b/parts/django/docs/ref/generic-views.txt
@@ -0,0 +1,1095 @@
+=============
+Generic views
+=============
+
+Writing Web applications can be monotonous, because we repeat certain patterns
+again and again. In Django, the most common of these patterns have been
+abstracted into "generic views" that let you quickly provide common views of
+an object without actually needing to write any Python code.
+
+A general introduction to generic views can be found in the :doc:`topic guide
+</topics/http/generic-views>`.
+
+This reference contains details of Django's built-in generic views, along with
+a list of all keyword arguments that a generic view expects. Remember that
+arguments may either come from the URL pattern or from the ``extra_context``
+additional-information dictionary.
+
+Most generic views require the ``queryset`` key, which is a ``QuerySet``
+instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
+objects.
+
+"Simple" generic views
+======================
+
+The ``django.views.generic.simple`` module contains simple views to handle a
+couple of common cases: rendering a template when no view logic is needed,
+and issuing a redirect.
+
+``django.views.generic.simple.direct_to_template``
+--------------------------------------------------
+
+**Description:**
+
+Renders a given template, passing it a ``{{ params }}`` template variable,
+which is a dictionary of the parameters captured in the URL.
+
+**Required arguments:**
+
+    * ``template``: The full name of a template to use.
+
+**Optional arguments:**
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+**Example:**
+
+Given the following URL patterns::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        (r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}),
+        (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
+    )
+
+... a request to ``/foo/`` would render the template ``foo_index.html``, and a
+request to ``/foo/15/`` would render the ``foo_detail.html`` with a context
+variable ``{{ params.id }}`` that is set to ``15``.
+
+``django.views.generic.simple.redirect_to``
+-------------------------------------------
+
+**Description:**
+
+Redirects to a given URL.
+
+The given URL may contain dictionary-style string formatting, which will be
+interpolated against the parameters captured in the URL. Because keyword
+interpolation is *always* done (even if no arguments are passed in), any ``"%"``
+characters in the URL must be written as ``"%%"`` so that Python will convert
+them to a single percent sign on output.
+
+If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410).
+
+**Required arguments:**
+
+    * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410
+      (Gone) HTTP error.
+
+**Optional arguments:**
+
+    * ``permanent``: Whether the redirect should be permanent. The only
+      difference here is the HTTP status code returned. If ``True``, then the
+      redirect will use status code 301. If ``False``, then the redirect will
+      use status code 302. By default, ``permanent`` is ``True``.
+
+.. versionadded:: 1.1
+    The ``permanent`` keyword argument is new in Django 1.1.
+
+**Example:**
+
+This example issues a permanent redirect (HTTP status code 301) from
+``/foo/<id>/`` to ``/bar/<id>/``::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
+    )
+
+This example issues a non-permanent redirect (HTTP status code 302) from
+``/foo/<id>/`` to ``/bar/<id>/``::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}),
+    )
+
+This example returns a 410 HTTP error for requests to ``/bar/``::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        ('^bar/$', 'redirect_to', {'url': None}),
+    )
+
+This example shows how ``"%"`` characters must be written in the URL in order
+to avoid confusion with Python's string formatting markers. If the redirect
+string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised::
+
+    urlpatterns = patterns('django.views.generic.simple',
+        ('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}),
+    )
+
+Date-based generic views
+========================
+
+Date-based generic views (in the module ``django.views.generic.date_based``)
+are views for displaying drilldown pages for date-based data.
+
+``django.views.generic.date_based.archive_index``
+-------------------------------------------------
+
+**Description:**
+
+A top-level index page showing the "latest" objects, by date. Objects with
+a date in the *future* are not included unless you set ``allow_future`` to
+``True``.
+
+**Required arguments:**
+
+    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the date-based archive should use to
+      determine the objects on the page.
+
+**Optional arguments:**
+
+    * ``num_latest``: The number of latest objects to send to the template
+      context. By default, it's 15.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``True``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+    .. versionadded:: 1.0
+
+    * ``template_object_name``: Designates the name of the template variable
+      to use in the template context. By default, this is ``'latest'``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive.html`` by default, where:
+
+    * ``<model_name>`` is your model's name in all lowercase. For a model
+      ``StaffMember``, that'd be ``staffmember``.
+
+    * ``<app_label>`` is the right-most part of the full Python path to
+      your model's app. For example, if your model lives in
+      ``apps/blog/models.py``, that'd be ``blog``.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``date_list``: A ``DateQuerySet`` object containing all years that have
+      have objects available according to ``queryset``, represented as
+      ``datetime.datetime`` objects. These are ordered in reverse. This is
+      equivalent to ``queryset.dates(date_field, 'year')[::-1]``.
+
+    .. versionchanged:: 1.0
+       The behaviour depending on ``template_object_name`` is new in this version.
+
+    * ``latest``: The ``num_latest`` objects in the system, ordered descending
+      by ``date_field``. For example, if ``num_latest`` is ``10``, then
+      ``latest`` will be a list of the latest 10 objects in ``queryset``.
+
+      This variable's name depends on the ``template_object_name`` parameter,
+      which is ``'latest'`` by default. If ``template_object_name`` is
+      ``'foo'``, this variable's name will be ``foo``.
+
+``django.views.generic.date_based.archive_year``
+------------------------------------------------
+
+**Description:**
+
+A yearly archive page showing all available months in a given year. Objects
+with a date in the *future* are not displayed unless you set ``allow_future``
+to ``True``.
+
+**Required arguments:**
+
+    * ``year``: The four-digit year for which the archive serves.
+
+    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the date-based archive should use to
+      determine the objects on the page.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``False``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``. The
+      view will append ``'_list'`` to the value of this parameter in
+      determining the variable's name.
+
+    * ``make_object_list``: A boolean specifying whether to retrieve the full
+      list of objects for this year and pass those to the template. If ``True``,
+      this list of objects will be made available to the template as
+      ``object_list``. (The name ``object_list`` may be different; see the docs
+      for ``object_list`` in the "Template context" section below.) By default,
+      this is ``False``.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_year.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``date_list``: A ``DateQuerySet`` object containing all months that have
+      have objects available according to ``queryset``, represented as
+      ``datetime.datetime`` objects, in ascending order.
+
+    * ``year``: The given year, as a four-character string.
+
+    * ``object_list``: If the ``make_object_list`` parameter is ``True``, this
+      will be set to a list of objects available for the given year, ordered by
+      the date field. This variable's name depends on the
+      ``template_object_name`` parameter, which is ``'object'`` by default. If
+      ``template_object_name`` is ``'foo'``, this variable's name will be
+      ``foo_list``.
+
+      If ``make_object_list`` is ``False``, ``object_list`` will be passed to
+      the template as an empty list.
+
+``django.views.generic.date_based.archive_month``
+-------------------------------------------------
+
+**Description:**
+
+A monthly archive page showing all objects in a given month. Objects with a
+date in the *future* are not displayed unless you set ``allow_future`` to
+``True``.
+
+**Required arguments:**
+
+    * ``year``: The four-digit year for which the archive serves (a string).
+
+    * ``month``: The month for which the archive serves, formatted according to
+      the ``month_format`` argument.
+
+    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the date-based archive should use to
+      determine the objects on the page.
+
+**Optional arguments:**
+
+    * ``month_format``: A format string that regulates what format the
+      ``month`` parameter uses. This should be in the syntax accepted by
+      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
+      ``"%b"`` by default, which is a three-letter month abbreviation. To
+      change it to use numbers, use ``"%m"``.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``False``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``. The
+      view will append ``'_list'`` to the value of this parameter in
+      determining the variable's name.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_month.html`` by default.
+
+**Template context:**
+
+.. versionadded:: 1.2
+   The inclusion of ``date_list`` in the template's context is new.
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``date_list``: A ``DateQuerySet`` object containing all days that have
+      have objects available in the given month, according to ``queryset``,
+      represented as ``datetime.datetime`` objects, in ascending order.
+
+    * ``month``: A ``datetime.date`` object representing the given month.
+
+    * ``next_month``: A ``datetime.date`` object representing the first day of
+      the next month. If the next month is in the future, this will be
+      ``None``.
+
+    * ``previous_month``: A ``datetime.date`` object representing the first day
+      of the previous month. Unlike ``next_month``, this will never be
+      ``None``.
+
+    * ``object_list``: A list of objects available for the given month. This
+      variable's name depends on the ``template_object_name`` parameter, which
+      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
+      this variable's name will be ``foo_list``.
+
+.. _strftime docs: http://docs.python.org/library/time.html#time.strftime
+
+``django.views.generic.date_based.archive_week``
+------------------------------------------------
+
+**Description:**
+
+A weekly archive page showing all objects in a given week. Objects with a date
+in the *future* are not displayed unless you set ``allow_future`` to ``True``.
+
+**Required arguments:**
+
+    * ``year``: The four-digit year for which the archive serves (a string).
+
+    * ``week``: The week of the year for which the archive serves (a string).
+      Weeks start with Sunday.
+
+    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the date-based archive should use to
+      determine the objects on the page.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``True``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``. The
+      view will append ``'_list'`` to the value of this parameter in
+      determining the variable's name.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_week.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``week``: A ``datetime.date`` object representing the first day of the
+      given week.
+
+    * ``object_list``: A list of objects available for the given week. This
+      variable's name depends on the ``template_object_name`` parameter, which
+      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
+      this variable's name will be ``foo_list``.
+
+``django.views.generic.date_based.archive_day``
+-----------------------------------------------
+
+**Description:**
+
+A day archive page showing all objects in a given day. Days in the future throw
+a 404 error, regardless of whether any objects exist for future days, unless
+you set ``allow_future`` to ``True``.
+
+**Required arguments:**
+
+    * ``year``: The four-digit year for which the archive serves (a string).
+
+    * ``month``: The month for which the archive serves, formatted according to
+      the ``month_format`` argument.
+
+    * ``day``: The day for which the archive serves, formatted according to the
+      ``day_format`` argument.
+
+    * ``queryset``: A ``QuerySet`` of objects for which the archive serves.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the date-based archive should use to
+      determine the objects on the page.
+
+**Optional arguments:**
+
+    * ``month_format``: A format string that regulates what format the
+      ``month`` parameter uses. This should be in the syntax accepted by
+      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
+      ``"%b"`` by default, which is a three-letter month abbreviation. To
+      change it to use numbers, use ``"%m"``.
+
+    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
+      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``False``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``. The
+      view will append ``'_list'`` to the value of this parameter in
+      determining the variable's name.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_archive_day.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``day``: A ``datetime.date`` object representing the given day.
+
+    * ``next_day``: A ``datetime.date`` object representing the next day. If
+      the next day is in the future, this will be ``None``.
+
+    * ``previous_day``: A ``datetime.date`` object representing the previous day.
+      Unlike ``next_day``, this will never be ``None``.
+
+    * ``object_list``: A list of objects available for the given day. This
+      variable's name depends on the ``template_object_name`` parameter, which
+      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
+      this variable's name will be ``foo_list``.
+
+``django.views.generic.date_based.archive_today``
+-------------------------------------------------
+
+**Description:**
+
+A day archive page showing all objects for *today*. This is exactly the same as
+``archive_day``, except the ``year``/``month``/``day`` arguments are not used,
+and today's date is used instead.
+
+``django.views.generic.date_based.object_detail``
+-------------------------------------------------
+
+**Description:**
+
+A page representing an individual object. If the object has a date value in the
+future, the view will throw a 404 error by default, unless you set
+``allow_future`` to ``True``.
+
+**Required arguments:**
+
+    * ``year``: The object's four-digit year (a string).
+
+    * ``month``: The object's month , formatted according to the
+      ``month_format`` argument.
+
+    * ``day``: The object's day , formatted according to the ``day_format``
+      argument.
+
+    * ``queryset``: A ``QuerySet`` that contains the object.
+
+    * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in
+      the ``QuerySet``'s model that the generic view should use to look up the
+      object according to ``year``, ``month`` and ``day``.
+
+    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+      If you provide ``object_id``, it should be the value of the primary-key
+      field for the object being displayed on this page.
+
+      Otherwise, ``slug`` should be the slug of the given object, and
+      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+      model. By default, ``slug_field`` is ``'slug'``.
+
+**Optional arguments:**
+
+    * ``month_format``: A format string that regulates what format the
+      ``month`` parameter uses. This should be in the syntax accepted by
+      Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
+      ``"%b"`` by default, which is a three-letter month abbreviation. To
+      change it to use numbers, use ``"%m"``.
+
+    * ``day_format``: Like ``month_format``, but for the ``day`` parameter.
+      It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_name_field``: The name of a field on the object whose value is
+      the template name to use. This lets you store template names in the data.
+      In other words, if your object has a field ``'the_template'`` that
+      contains a string ``'foo.html'``, and you set ``template_name_field`` to
+      ``'the_template'``, then the generic view for this object will use the
+      template ``'foo.html'``.
+
+      It's a bit of a brain-bender, but it's useful in some cases.
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+    * ``allow_future``: A boolean specifying whether to include "future"
+      objects on this page, where "future" means objects in which the field
+      specified in ``date_field`` is greater than the current date/time. By
+      default, this is ``False``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_detail.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``object``: The object. This variable's name depends on the
+      ``template_object_name`` parameter, which is ``'object'`` by default. If
+      ``template_object_name`` is ``'foo'``, this variable's name will be
+      ``foo``.
+
+List/detail generic views
+=========================
+
+The list-detail generic-view framework (in the
+``django.views.generic.list_detail`` module) is similar to the date-based one,
+except the former simply has two views: a list of objects and an individual
+object page.
+
+``django.views.generic.list_detail.object_list``
+------------------------------------------------
+
+**Description:**
+
+A page representing a list of objects.
+
+**Required arguments:**
+
+    * ``queryset``: A ``QuerySet`` that represents the objects.
+
+**Optional arguments:**
+
+    * ``paginate_by``: An integer specifying how many objects should be
+      displayed per page. If this is given, the view will paginate objects with
+      ``paginate_by`` objects per page. The view will expect either a ``page``
+      query string parameter (via ``GET``) or a ``page`` variable specified in
+      the URLconf. See `Notes on pagination`_ below.
+
+    * ``page``: The current page number, as an integer, or the string
+      ``'last'``. This is 1-based. See `Notes on pagination`_ below.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``allow_empty``: A boolean specifying whether to display the page if no
+      objects are available. If this is ``False`` and no objects are available,
+      the view will raise a 404 instead of displaying an empty page. By
+      default, this is ``True``.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``. The
+      view will append ``'_list'`` to the value of this parameter in
+      determining the variable's name.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_list.html`` by default.
+
+**Template context:**
+
+.. versionadded:: 1.0
+   The ``paginator`` and ``page_obj`` context variables are new.
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``object_list``: The list of objects. This variable's name depends on the
+      ``template_object_name`` parameter, which is ``'object'`` by default. If
+      ``template_object_name`` is ``'foo'``, this variable's name will be
+      ``foo_list``.
+
+    * ``is_paginated``: A boolean representing whether the results are
+      paginated. Specifically, this is set to ``False`` if the number of
+      available objects is less than or equal to ``paginate_by``.
+
+If the results are paginated, the context will contain these extra variables:
+
+    * ``paginator``: An instance of ``django.core.paginator.Paginator``.
+
+    * ``page_obj``: An instance of ``django.core.paginator.Page``.
+
+Notes on pagination
+~~~~~~~~~~~~~~~~~~~
+
+If ``paginate_by`` is specified, Django will paginate the results. You can
+specify the page number in the URL in one of two ways:
+
+    * Use the ``page`` parameter in the URLconf. For example, this is what
+      your URLconf might look like::
+
+        (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))
+
+    * Pass the page number via the ``page`` query-string parameter. For
+      example, a URL would look like this::
+
+        /objects/?page=3
+
+    * To loop over all the available page numbers, use the ``page_range``
+      variable. You can iterate over the list provided by ``page_range``
+      to create a link to every page of results.
+
+These values and lists are 1-based, not 0-based, so the first page would be
+represented as page ``1``.
+
+For more on pagination, read the :doc:`pagination documentation
+</topics/pagination>`.
+
+.. versionadded:: 1.0
+
+As a special case, you are also permitted to use ``last`` as a value for
+``page``::
+
+    /objects/?page=last
+
+This allows you to access the final page of results without first having to
+determine how many pages there are.
+
+Note that ``page`` *must* be either a valid page number or the value ``last``;
+any other value for ``page`` will result in a 404 error.
+
+``django.views.generic.list_detail.object_detail``
+--------------------------------------------------
+
+A page representing an individual object.
+
+**Description:**
+
+A page representing an individual object.
+
+**Required arguments:**
+
+    * ``queryset``: A ``QuerySet`` that contains the object.
+
+    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+      If you provide ``object_id``, it should be the value of the primary-key
+      field for the object being displayed on this page.
+
+      Otherwise, ``slug`` should be the slug of the given object, and
+      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+      model. By default, ``slug_field`` is ``'slug'``.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_name_field``: The name of a field on the object whose value is
+      the template name to use. This lets you store template names in the data.
+      In other words, if your object has a field ``'the_template'`` that
+      contains a string ``'foo.html'``, and you set ``template_name_field`` to
+      ``'the_template'``, then the generic view for this object will use the
+      template ``'foo.html'``.
+
+      It's a bit of a brain-bender, but it's useful in some cases.
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``.
+
+    * ``mimetype``: The MIME type to use for the resulting document. Defaults
+      to the value of the ``DEFAULT_CONTENT_TYPE`` setting.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_detail.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``object``: The object. This variable's name depends on the
+      ``template_object_name`` parameter, which is ``'object'`` by default. If
+      ``template_object_name`` is ``'foo'``, this variable's name will be
+      ``foo``.
+
+Create/update/delete generic views
+==================================
+
+The ``django.views.generic.create_update`` module contains a set of functions
+for creating, editing and deleting objects.
+
+.. versionchanged:: 1.0
+
+``django.views.generic.create_update.create_object`` and
+``django.views.generic.create_update.update_object`` now use the new :doc:`forms
+library </topics/forms/index>` to build and display the form.
+
+``django.views.generic.create_update.create_object``
+----------------------------------------------------
+
+**Description:**
+
+A page that displays a form for creating an object, redisplaying the form with
+validation errors (if there are any) and saving the object.
+
+**Required arguments:**
+
+    * Either ``form_class`` or ``model`` is required.
+
+      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
+      subclass. Use this argument when you need to customize the model's form.
+      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
+      information.
+
+      Otherwise, ``model`` should be a Django model class and the form used
+      will be a standard ``ModelForm`` for ``model``.
+
+**Optional arguments:**
+
+    * ``post_save_redirect``: A URL to which the view will redirect after
+      saving the object. By default, it's ``object.get_absolute_url()``.
+
+      ``post_save_redirect`` may contain dictionary string formatting, which
+      will be interpolated against the object's field attributes. For example,
+      you could use ``post_save_redirect="/polls/%(slug)s/"``.
+
+    * ``login_required``: A boolean that designates whether a user must be
+      logged in, in order to see the page and save changes. This hooks into the
+      Django :doc:`authentication system </topics/auth>`. By default, this is
+      ``False``.
+
+      If this is ``True``, and a non-logged-in user attempts to visit this page
+      or save the form, Django will redirect the request to ``/accounts/login/``.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_form.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``form``: A ``django.forms.ModelForm`` instance representing the form
+      for creating the object. This lets you refer to form fields easily in the
+      template system.
+
+      For example, if the model has two fields, ``name`` and ``address``::
+
+          <form action="" method="post">
+          <p>{{ form.name.label_tag }} {{ form.name }}</p>
+          <p>{{ form.address.label_tag }} {{ form.address }}</p>
+          </form>
+
+      See the :doc:`forms documentation </topics/forms/index>` for more
+      information about using ``Form`` objects in templates.
+
+``django.views.generic.create_update.update_object``
+----------------------------------------------------
+
+**Description:**
+
+A page that displays a form for editing an existing object, redisplaying the
+form with validation errors (if there are any) and saving changes to the
+object. This uses a form automatically generated from the object's
+model class.
+
+**Required arguments:**
+
+    * Either ``form_class`` or ``model`` is required.
+
+      If you provide ``form_class``, it should be a ``django.forms.ModelForm``
+      subclass. Use this argument when you need to customize the model's form.
+      See the :doc:`ModelForm docs </topics/forms/modelforms>` for more
+      information.
+
+      Otherwise, ``model`` should be a Django model class and the form used
+      will be a standard ``ModelForm`` for ``model``.
+
+    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+      If you provide ``object_id``, it should be the value of the primary-key
+      field for the object being displayed on this page.
+
+      Otherwise, ``slug`` should be the slug of the given object, and
+      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+      model. By default, ``slug_field`` is ``'slug'``.
+
+**Optional arguments:**
+
+    * ``post_save_redirect``: A URL to which the view will redirect after
+      saving the object. By default, it's ``object.get_absolute_url()``.
+
+      ``post_save_redirect`` may contain dictionary string formatting, which
+      will be interpolated against the object's field attributes. For example,
+      you could use ``post_save_redirect="/polls/%(slug)s/"``.
+
+    * ``login_required``: A boolean that designates whether a user must be
+      logged in, in order to see the page and save changes. This hooks into the
+      Django :doc:`authentication system </topics/auth>`. By default, this is
+      ``False``.
+
+      If this is ``True``, and a non-logged-in user attempts to visit this page
+      or save the form, Django will redirect the request to ``/accounts/login/``.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_form.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``form``: A ``django.forms.ModelForm`` instance representing the form
+      for editing the object. This lets you refer to form fields easily in the
+      template system.
+
+      For example, if the model has two fields, ``name`` and ``address``::
+
+          <form action="" method="post">
+          <p>{{ form.name.label_tag }} {{ form.name }}</p>
+          <p>{{ form.address.label_tag }} {{ form.address }}</p>
+          </form>
+
+      See the :doc:`forms documentation </topics/forms/index>` for more
+      information about using ``Form`` objects in templates.
+
+    * ``object``: The original object being edited. This variable's name
+      depends on the ``template_object_name`` parameter, which is ``'object'``
+      by default. If ``template_object_name`` is ``'foo'``, this variable's
+      name will be ``foo``.
+
+``django.views.generic.create_update.delete_object``
+----------------------------------------------------
+
+**Description:**
+
+A view that displays a confirmation page and deletes an existing object. The
+given object will only be deleted if the request method is ``POST``. If this
+view is fetched via ``GET``, it will display a confirmation page that should
+contain a form that POSTs to the same URL.
+
+**Required arguments:**
+
+    * ``model``: The Django model class of the object that the form will
+      create.
+
+    * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required.
+
+      If you provide ``object_id``, it should be the value of the primary-key
+      field for the object being displayed on this page.
+
+      Otherwise, ``slug`` should be the slug of the given object, and
+      ``slug_field`` should be the name of the slug field in the ``QuerySet``'s
+      model. By default, ``slug_field`` is ``'slug'``.
+
+    * ``post_delete_redirect``: A URL to which the view will redirect after
+      deleting the object.
+
+**Optional arguments:**
+
+    * ``login_required``: A boolean that designates whether a user must be
+      logged in, in order to see the page and save changes. This hooks into the
+      Django :doc:`authentication system </topics/auth>`. By default, this is
+      ``False``.
+
+      If this is ``True``, and a non-logged-in user attempts to visit this page
+      or save the form, Django will redirect the request to ``/accounts/login/``.
+
+    * ``template_name``: The full name of a template to use in rendering the
+      page. This lets you override the default template name (see below).
+
+    * ``template_loader``: The template loader to use when loading the
+      template. By default, it's ``django.template.loader``.
+
+    * ``extra_context``: A dictionary of values to add to the template
+      context. By default, this is an empty dictionary. If a value in the
+      dictionary is callable, the generic view will call it
+      just before rendering the template.
+
+    * ``context_processors``: A list of template-context processors to apply to
+      the view's template.
+
+    * ``template_object_name``:  Designates the name of the template variable
+      to use in the template context. By default, this is ``'object'``.
+
+**Template name:**
+
+If ``template_name`` isn't specified, this view will use the template
+``<app_label>/<model_name>_confirm_delete.html`` by default.
+
+**Template context:**
+
+In addition to ``extra_context``, the template's context will be:
+
+    * ``object``: The original object that's about to be deleted. This
+      variable's name depends on the ``template_object_name`` parameter, which
+      is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
+      this variable's name will be ``foo``.
diff --git a/parts/django/docs/ref/index.txt b/parts/django/docs/ref/index.txt
new file mode 100644
index 0000000..0919417
--- /dev/null
+++ b/parts/django/docs/ref/index.txt
@@ -0,0 +1,24 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   authbackends
+   contrib/index
+   databases
+   django-admin
+   exceptions
+   files/index
+   forms/index
+   generic-views
+   middleware
+   models/index
+   request-response
+   settings
+   signals
+   templates/index
+   unicode
+   utils
+   validators
diff --git a/parts/django/docs/ref/middleware.txt b/parts/django/docs/ref/middleware.txt
new file mode 100644
index 0000000..b3ddb23
--- /dev/null
+++ b/parts/django/docs/ref/middleware.txt
@@ -0,0 +1,212 @@
+==========
+Middleware
+==========
+
+.. module:: django.middleware
+   :synopsis: Django's built-in middleware classes.
+
+This document explains all middleware components that come with Django. For
+information on how how to use them and how to write your own middleware, see
+the :doc:`middleware usage guide </topics/http/middleware>`.
+
+Available middleware
+====================
+
+Cache middleware
+----------------
+
+.. module:: django.middleware.cache
+   :synopsis: Middleware for the site-wide cache.
+
+.. class:: UpdateCacheMiddleware
+
+.. class:: FetchFromCacheMiddleware
+
+Enable the site-wide cache. If these are enabled, each Django-powered page will
+be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting
+defines. See the :doc:`cache documentation </topics/cache>`.
+
+"Common" middleware
+-------------------
+
+.. module:: django.middleware.common
+   :synopsis: Middleware adding "common" conveniences for perfectionists.
+
+.. class:: CommonMiddleware
+
+Adds a few conveniences for perfectionists:
+
+    * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS`
+      setting, which should be a list of strings.
+
+    * Performs URL rewriting based on the :setting:`APPEND_SLASH` and
+      :setting:`PREPEND_WWW` settings.
+
+      If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end
+      with a slash, and it is not found in the URLconf, then a new URL is
+      formed by appending a slash at the end. If this new URL is found in the
+      URLconf, then Django redirects the request to this new URL. Otherwise,
+      the initial URL is processed as usual.
+
+      For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if
+      you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a
+      valid pattern for ``foo.com/bar/``.
+
+      .. versionchanged:: 1.0
+         The behavior of :setting:`APPEND_SLASH` has changed slightly in this
+         version. It didn't used to check whether the pattern was matched in
+         the URLconf.
+
+      If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www."
+      will be redirected to the same URL with a leading "www."
+
+      Both of these options are meant to normalize URLs. The philosophy is that
+      each URL should exist in one, and only one, place. Technically a URL
+      ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine
+      indexer would treat them as separate URLs -- so it's best practice to
+      normalize URLs.
+
+    * Sends broken link notification emails to :setting:`MANAGERS` if
+      :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``.
+
+    * Handles ETags based on the :setting:`USE_ETAGS` setting. If
+      :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag
+      for each request by MD5-hashing the page content, and it'll take care of
+      sending ``Not Modified`` responses, if appropriate.
+
+View metadata middleware
+------------------------
+
+.. module:: django.middleware.doc
+   :synopsis: Middleware to help your app self-document.
+
+.. class:: XViewMiddleware
+
+Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
+addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by
+Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`.
+
+GZIP middleware
+---------------
+
+.. module:: django.middleware.gzip
+   :synopsis: Middleware to serve gziped content for performance.
+
+.. class:: GZipMiddleware
+
+Compresses content for browsers that understand gzip compression (all modern
+browsers).
+
+It is suggested to place this first in the middleware list, so that the
+compression of the response content is the last thing that happens. Will not
+compress content bodies less than 200 bytes long, when the response code is
+something other than 200, JavaScript files (for IE compatibility), or
+responses that have the ``Content-Encoding`` header already specified.
+
+Conditional GET middleware
+--------------------------
+
+.. module:: django.middleware.http
+   :synopsis: Middleware handling advanced HTTP features.
+
+.. class:: ConditionalGetMiddleware
+
+Handles conditional GET operations. If the response has a ``ETag`` or
+``Last-Modified`` header, and the request has ``If-None-Match`` or
+``If-Modified-Since``, the response is replaced by an
+:class:`~django.http.HttpNotModified`.
+
+Also sets the ``Date`` and ``Content-Length`` response-headers.
+
+Reverse proxy middleware
+------------------------
+
+.. class:: SetRemoteAddrFromForwardedFor
+
+.. versionchanged:: 1.1
+
+This middleware was removed in Django 1.1. See :ref:`the release notes
+<removed-setremoteaddrfromforwardedfor-middleware>` for details.
+
+Locale middleware
+-----------------
+
+.. module:: django.middleware.locale
+   :synopsis: Middleware to enable language selection based on the request.
+
+.. class:: LocaleMiddleware
+
+Enables language selection based on data from the request. It customizes
+content for each user. See the :doc:`internationalization documentation
+</topics/i18n/index>`.
+
+Message middleware
+------------------
+
+.. module:: django.contrib.messages.middleware
+   :synopsis: Message middleware.
+
+.. class:: MessageMiddleware
+
+.. versionadded:: 1.2
+   ``MessageMiddleware`` was added.
+
+Enables cookie- and session-based message support. See the
+:doc:`messages documentation </ref/contrib/messages>`.
+
+Session middleware
+------------------
+
+.. module:: django.contrib.sessions.middleware
+   :synopsis: Session middleware.
+
+.. class:: SessionMiddleware
+
+Enables session support. See the :doc:`session documentation
+</topics/http/sessions>`.
+
+Authentication middleware
+-------------------------
+
+.. module:: django.contrib.auth.middleware
+  :synopsis: Authentication middleware.
+
+.. class:: AuthenticationMiddleware
+
+Adds the ``user`` attribute, representing the currently-logged-in user, to
+every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests
+</topics/auth>`.
+
+CSRF protection middleware
+--------------------------
+
+.. module:: django.middleware.csrf
+   :synopsis: Middleware adding protection against Cross Site Request
+              Forgeries.
+
+.. class:: CsrfMiddleware
+
+.. versionadded:: 1.0
+
+Adds protection against Cross Site Request Forgeries by adding hidden form
+fields to POST forms and checking requests for the correct value. See the
+:doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`.
+
+Transaction middleware
+----------------------
+
+.. module:: django.middleware.transaction
+   :synopsis: Middleware binding a database transaction to each Web request.
+
+.. class:: TransactionMiddleware
+
+Binds commit and rollback to the request/response phase. If a view function
+runs successfully, a commit is done. If it fails with an exception, a rollback
+is done.
+
+The order of this middleware in the stack is important: middleware modules
+running outside of it run with commit-on-save - the default Django behavior.
+Middleware modules running inside it (coming later in the stack) will be under
+the same transaction control as the view functions.
+
+See the :doc:`transaction management documentation </topics/db/transactions>`.
diff --git a/parts/django/docs/ref/models/fields.txt b/parts/django/docs/ref/models/fields.txt
new file mode 100644
index 0000000..146ca43
--- /dev/null
+++ b/parts/django/docs/ref/models/fields.txt
@@ -0,0 +1,1063 @@
+=====================
+Model field reference
+=====================
+
+.. module:: django.db.models.fields
+   :synopsis: Built-in field types.
+
+.. currentmodule:: django.db.models
+
+This document contains all the gory details about all the `field options`_ and
+`field types`_ Django's got to offer.
+
+.. seealso::
+
+    If the built-in fields don't do the trick, you can easily :doc:`write your
+    own custom model fields </howto/custom-model-fields>`.
+
+.. note::
+
+    Technically, these models are defined in :mod:`django.db.models.fields`, but
+    for convenience they're imported into :mod:`django.db.models`; the standard
+    convention is to use ``from django.db import models`` and refer to fields as
+    ``models.<Foo>Field``.
+
+.. _common-model-field-options:
+
+Field options
+=============
+
+The following arguments are available to all field types. All are optional.
+
+``null``
+--------
+
+.. attribute:: Field.null
+
+If ``True``, Django will store empty values as ``NULL`` in the database. Default
+is ``False``.
+
+Note that empty string values will always get stored as empty strings, not as
+``NULL``. Only use ``null=True`` for non-string fields such as integers,
+booleans and dates. For both types of fields, you will also need to set
+``blank=True`` if you wish to permit empty values in forms, as the
+:attr:`~Field.null` parameter only affects database storage (see
+:attr:`~Field.blank`).
+
+Avoid using :attr:`~Field.null` on string-based fields such as
+:class:`CharField` and :class:`TextField` unless you have an excellent reason.
+If a string-based field has ``null=True``, that means it has two possible values
+for "no data": ``NULL``, and the empty string. In most cases, it's redundant to
+have two possible values for "no data;" Django convention is to use the empty
+string, not ``NULL``.
+
+.. note::
+
+    When using the Oracle database backend, the ``null=True`` option will be
+    coerced for string-based fields that have the empty string as a possible
+    value, and the value ``NULL`` will be stored to denote the empty string.
+
+``blank``
+---------
+
+.. attribute:: Field.blank
+
+If ``True``, the field is allowed to be blank. Default is ``False``.
+
+Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is
+purely database-related, whereas :attr:`~Field.blank` is validation-related. If
+a field has ``blank=True``, validation on Django's admin site will allow entry
+of an empty value. If a field has ``blank=False``, the field will be required.
+
+.. _field-choices:
+
+``choices``
+-----------
+
+.. attribute:: Field.choices
+
+An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
+field.
+
+If this is given, Django's admin will use a select box instead of the standard
+text field and will limit choices to the choices given.
+
+A choices list looks like this::
+
+    YEAR_IN_SCHOOL_CHOICES = (
+        ('FR', 'Freshman'),
+        ('SO', 'Sophomore'),
+        ('JR', 'Junior'),
+        ('SR', 'Senior'),
+        ('GR', 'Graduate'),
+    )
+
+The first element in each tuple is the actual value to be stored. The second
+element is the human-readable name for the option.
+
+The choices list can be defined either as part of your model class::
+
+    class Foo(models.Model):
+        GENDER_CHOICES = (
+            ('M', 'Male'),
+            ('F', 'Female'),
+        )
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+
+or outside your model class altogether::
+
+    GENDER_CHOICES = (
+        ('M', 'Male'),
+        ('F', 'Female'),
+    )
+    class Foo(models.Model):
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+
+You can also collect your available choices into named groups that can
+be used for organizational purposes::
+
+    MEDIA_CHOICES = (
+        ('Audio', (
+                ('vinyl', 'Vinyl'),
+                ('cd', 'CD'),
+            )
+        ),
+        ('Video', (
+                ('vhs', 'VHS Tape'),
+                ('dvd', 'DVD'),
+            )
+        ),
+        ('unknown', 'Unknown'),
+    )
+
+The first element in each tuple is the name to apply to the group. The
+second element is an iterable of 2-tuples, with each 2-tuple containing
+a value and a human-readable name for an option. Grouped options may be
+combined with ungrouped options within a single list (such as the
+`unknown` option in this example).
+
+For each model field that has :attr:`~Field.choices` set, Django will add a
+method to retrieve the human-readable name for the field's current value. See
+:meth:`~django.db.models.Model.get_FOO_display` in the database API
+documentation.
+
+Finally, note that choices can be any iterable object -- not necessarily a list
+or tuple. This lets you construct choices dynamically. But if you find yourself
+hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a
+proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
+meant for static data that doesn't change much, if ever.
+
+``db_column``
+-------------
+
+.. attribute:: Field.db_column
+
+The name of the database column to use for this field. If this isn't given,
+Django will use the field's name.
+
+If your database column name is an SQL reserved word, or contains
+characters that aren't allowed in Python variable names -- notably, the
+hyphen -- that's OK. Django quotes column and table names behind the
+scenes.
+
+``db_index``
+------------
+
+.. attribute:: Field.db_index
+
+If ``True``, djadmin:`django-admin.py sqlindexes <sqlindexes>` will output a
+``CREATE INDEX`` statement for this field.
+
+``db_tablespace``
+-----------------
+
+.. attribute:: Field.db_tablespace
+
+.. versionadded:: 1.0
+
+The name of the database tablespace to use for this field's index, if this field
+is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE`
+setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If
+the backend doesn't support tablespaces, this option is ignored.
+
+``default``
+-----------
+
+.. attribute:: Field.default
+
+The default value for the field. This can be a value or a callable object. If
+callable it will be called every time a new object is created.
+
+``editable``
+------------
+
+.. attribute:: Field.editable
+
+If ``False``, the field will not be editable in the admin or via forms
+automatically generated from the model class. Default is ``True``.
+
+``error_messages``
+------------------
+
+.. versionadded:: 1.2
+
+.. attribute:: Field.error_messages
+
+The ``error_messages`` argument lets you override the default messages that the
+field will raise. Pass in a dictionary with keys matching the error messages you
+want to override.
+
+``help_text``
+-------------
+
+.. attribute:: Field.help_text
+
+Extra "help" text to be displayed under the field on the object's admin form.
+It's useful for documentation even if your object doesn't have an admin form.
+
+Note that this value is *not* HTML-escaped when it's displayed in the admin
+interface. This lets you include HTML in :attr:`~Field.help_text` if you so
+desire. For example::
+
+    help_text="Please use the following format: <em>YYYY-MM-DD</em>."
+
+Alternatively you can use plain text and
+``django.utils.html.escape()`` to escape any HTML special characters.
+
+``primary_key``
+---------------
+
+.. attribute:: Field.primary_key
+
+If ``True``, this field is the primary key for the model.
+
+If you don't specify ``primary_key=True`` for any fields in your model, Django
+will automatically add an :class:`IntegerField` to hold the primary key, so you
+don't need to set ``primary_key=True`` on any of your fields unless you want to
+override the default primary-key behavior. For more, see
+:ref:`automatic-primary-key-fields`.
+
+``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
+Only one primary key is allowed on an object.
+
+``unique``
+----------
+
+.. attribute:: Field.unique
+
+If ``True``, this field must be unique throughout the table.
+
+This is enforced at the database level and at the Django admin-form level. If
+you try to save a model with a duplicate value in a :attr:`~Field.unique`
+field, a :exc:`django.db.IntegrityError` will be raised by the model's
+:meth:`~django.db.models.Model.save` method.
+
+This option is valid on all field types except :class:`ManyToManyField` and
+:class:`FileField`.
+
+``unique_for_date``
+-------------------
+
+.. attribute:: Field.unique_for_date
+
+Set this to the name of a :class:`DateField` or :class:`DateTimeField` to
+require that this field be unique for the value of the date field.
+
+For example, if you have a field ``title`` that has
+``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two
+records with the same ``title`` and ``pub_date``.
+
+This is enforced at the Django admin-form level but not at the database level.
+
+``unique_for_month``
+--------------------
+
+.. attribute:: Field.unique_for_month
+
+Like :attr:`~Field.unique_for_date`, but requires the field to be unique with
+respect to the month.
+
+``unique_for_year``
+-------------------
+
+.. attribute:: Field.unique_for_year
+
+Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`.
+
+``verbose_name``
+-------------------
+
+.. attribute:: Field.verbose_name
+
+A human-readable name for the field. If the verbose name isn't given, Django
+will automatically create it using the field's attribute name, converting
+underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`.
+
+``validators``
+-------------------
+
+.. versionadded:: 1.2
+
+.. attribute:: Field.validators
+
+A list of validators to run for this field.See the :doc:`validators
+documentation </ref/validators>` for more information.
+
+.. _model-field-types:
+
+Field types
+===========
+
+.. currentmodule:: django.db.models
+
+``AutoField``
+-------------
+
+.. class:: AutoField(**options)
+
+An :class:`IntegerField` that automatically increments
+according to available IDs. You usually won't need to use this directly; a
+primary key field will automatically be added to your model if you don't specify
+otherwise. See :ref:`automatic-primary-key-fields`.
+
+``BigIntegerField``
+-------------------
+
+.. versionadded:: 1.2
+
+.. class:: BigIntegerField([**options])
+
+A 64 bit integer, much like an :class:`IntegerField` except that it is
+guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The
+admin represents this as an ``<input type="text">`` (a single-line input).
+
+
+``BooleanField``
+----------------
+
+.. class:: BooleanField(**options)
+
+A true/false field.
+
+The admin represents this as a checkbox.
+
+.. versionchanged:: 1.2
+
+    In previous versions of Django when running under MySQL ``BooleanFields``
+    would return their data as ``ints``, instead of true ``bools``.  See the
+    release notes for a complete description of the change.
+
+``CharField``
+-------------
+
+.. class:: CharField(max_length=None, [**options])
+
+A string field, for small- to large-sized strings.
+
+For large amounts of text, use :class:`~django.db.models.TextField`.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+:class:`CharField` has one extra required argument:
+
+.. attribute:: CharField.max_length
+
+    The maximum length (in characters) of the field. The max_length is enforced
+    at the database level and in Django's validation.
+
+.. note::
+
+    If you are writing an application that must be portable to multiple
+    database backends, you should be aware that there are restrictions on
+    ``max_length`` for some backends. Refer to the :doc:`database backend
+    notes </ref/databases>` for details.
+
+.. admonition:: MySQL users
+
+    If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin``
+    collation (which is *not* the default), there are some issues to be aware
+    of. Refer to the :ref:`MySQL database notes <mysql-collation>` for
+    details.
+
+
+``CommaSeparatedIntegerField``
+------------------------------
+
+.. class:: CommaSeparatedIntegerField(max_length=None, [**options])
+
+A field of integers separated by commas. As in :class:`CharField`, the
+:attr:`~CharField.max_length` argument is required and the note about database
+portability mentioned there should be heeded.
+
+``DateField``
+-------------
+
+.. class:: DateField([auto_now=False, auto_now_add=False, **options])
+
+A date, represented in Python by a ``datetime.date`` instance. Has a few extra,
+optional arguments:
+
+.. attribute:: DateField.auto_now
+
+    Automatically set the field to now every time the object is saved. Useful
+    for "last-modified" timestamps. Note that the current date is *always*
+    used; it's not just a default value that you can override.
+
+.. attribute:: DateField.auto_now_add
+
+    Automatically set the field to now when the object is first created. Useful
+    for creation of timestamps. Note that the current date is *always* used;
+    it's not just a default value that you can override.
+
+The admin represents this as an ``<input type="text">`` with a JavaScript
+calendar, and a shortcut for "Today".  The JavaScript calendar will always
+start the week on a Sunday.
+
+.. note::
+    As currently implemented, setting ``auto_now`` or ``auto_add_now`` to
+    ``True`` will cause the field to have ``editable=False`` and ``blank=True``
+    set.
+
+``DateTimeField``
+-----------------
+
+.. class:: DateTimeField([auto_now=False, auto_now_add=False, **options])
+
+A date and time, represented in Python by a ``datetime.datetime`` instance.
+Takes the same extra arguments as :class:`DateField`.
+
+The admin represents this as two ``<input type="text">`` fields, with
+JavaScript shortcuts.
+
+``DecimalField``
+----------------
+
+.. versionadded:: 1.0
+
+.. class:: DecimalField(max_digits=None, decimal_places=None, [**options])
+
+A fixed-precision decimal number, represented in Python by a
+:class:`~decimal.Decimal` instance. Has two **required** arguments:
+
+.. attribute:: DecimalField.max_digits
+
+    The maximum number of digits allowed in the number
+
+.. attribute:: DecimalField.decimal_places
+
+    The number of decimal places to store with the number
+
+For example, to store numbers up to 999 with a resolution of 2 decimal places,
+you'd use::
+
+    models.DecimalField(..., max_digits=5, decimal_places=2)
+
+And to store numbers up to approximately one billion with a resolution of 10
+decimal places::
+
+    models.DecimalField(..., max_digits=19, decimal_places=10)
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``EmailField``
+--------------
+
+.. class:: EmailField([max_length=75, **options])
+
+A :class:`CharField` that checks that the value is a valid e-mail address.
+
+``FileField``
+-------------
+
+.. class:: FileField(upload_to=None, [max_length=100, **options])
+
+A file-upload field.
+
+.. note::
+    The ``primary_key`` and ``unique`` arguments are not supported, and will
+    raise a ``TypeError`` if used.
+
+Has one **required** argument:
+
+.. attribute:: FileField.upload_to
+
+    A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
+    setting to determine the value of the :attr:`~django.core.files.File.url`
+    attribute.
+
+    This path may contain `strftime formatting`_, which will be replaced by the
+    date/time of the file upload (so that uploaded files don't fill up the given
+    directory).
+
+    .. versionchanged:: 1.0
+
+    This may also be a callable, such as a function, which will be called to
+    obtain the upload path, including the filename. This callable must be able
+    to accept two arguments, and return a Unix-style path (with forward slashes)
+    to be passed along to the storage system. The two arguments that will be
+    passed are:
+
+        ======================  ===============================================
+        Argument                Description
+        ======================  ===============================================
+        ``instance``            An instance of the model where the
+                                ``FileField`` is defined. More specifically,
+                                this is the particular instance where the
+                                current file is being attached.
+
+                                In most cases, this object will not have been
+                                saved to the database yet, so if it uses the
+                                default ``AutoField``, *it might not yet have a
+                                value for its primary key field*.
+
+        ``filename``            The filename that was originally given to the
+                                file. This may or may not be taken into account
+                                when determining the final destination path.
+        ======================  ===============================================
+
+Also has one optional argument:
+
+.. attribute:: FileField.storage
+
+    .. versionadded:: 1.0
+
+    Optional. A storage object, which handles the storage and retrieval of your
+    files. See :doc:`/topics/files` for details on how to provide this object.
+
+The admin represents this field as an ``<input type="file">`` (a file-upload
+widget).
+
+Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
+takes a few steps:
+
+    1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
+       full path to a directory where you'd like Django to store uploaded files.
+       (For performance, these files are not stored in the database.) Define
+       :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
+       that this directory is writable by the Web server's user account.
+
+    2. Add the :class:`FileField` or :class:`ImageField` to your model, making
+       sure to define the :attr:`~FileField.upload_to` option to tell Django
+       to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
+
+    3. All that will be stored in your database is a path to the file
+       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
+       convenience :attr:`~django.core.files.File.url` function provided by
+       Django. For example, if your :class:`ImageField` is called ``mug_shot``,
+       you can get the absolute path to your image in a template with
+       ``{{ object.mug_shot.url }}``.
+
+For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
+:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
+part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the
+four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit
+day. If you upload a file on Jan. 15, 2007, it will be saved in the directory
+``/home/media/photos/2007/01/15``.
+
+If you want to retrieve the upload file's on-disk filename, or a URL that refers
+to that file, or the file's size, you can use the
+:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url`
+and :attr:`~django.core.files.File.size` attributes; see :doc:`/topics/files`.
+
+Note that whenever you deal with uploaded files, you should pay close attention
+to where you're uploading them and what type of files they are, to avoid
+security holes. *Validate all uploaded files* so that you're sure the files are
+what you think they are. For example, if you blindly let somebody upload files,
+without validation, to a directory that's within your Web server's document
+root, then somebody could upload a CGI or PHP script and execute that script by
+visiting its URL on your site. Don't allow that.
+
+.. versionadded:: 1.0
+   The ``max_length`` argument was added in this version.
+
+By default, :class:`FileField` instances are
+created as ``varchar(100)`` columns in your database. As with other fields, you
+can change the maximum length using the :attr:`~CharField.max_length` argument.
+
+.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
+
+FileField and FieldFile
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When you access a :class:`FileField` on a model, you are given an instance
+of :class:`FieldFile` as a proxy for accessing the underlying file. This
+class has several methods that can be used to interact with file data:
+
+.. method:: FieldFile.open(mode='rb')
+
+Behaves like the standard Python ``open()`` method and opens the file
+associated with this instance in the mode specified by ``mode``.
+
+.. method:: FieldFile.close()
+
+Behaves like the standard Python ``file.close()`` method and closes the file
+associated with this instance.
+
+.. method:: FieldFile.save(name, content, save=True)
+
+This method takes a filename and file contents and passes them to the storage
+class for the field, then associates the stored file with the model field.
+If you want to manually associate file data with :class:`FileField`
+instances on your model, the ``save()`` method is used to persist that file
+data.
+
+Takes two required arguments: ``name`` which is the name of the file, and
+``content`` which is a file-like object containing the file's contents. The
+optional ``save`` argument controls whether or not the instance is saved after
+the file has been altered. Defaults to ``True``.
+
+.. method:: FieldFile.delete(save=True)
+
+Deletes the file associated with this instance and clears all attributes on
+the field. Note: This method will close the file if it happens to be open when
+``delete()`` is called.
+
+The optional ``save`` argument controls whether or not the instance is saved
+after the file has been deleted. Defaults to ``True``.
+
+``FilePathField``
+-----------------
+
+.. class:: FilePathField(path=None, [match=None, recursive=False, max_length=100, **options])
+
+A :class:`CharField` whose choices are limited to the filenames in a certain
+directory on the filesystem. Has three special arguments, of which the first is
+**required**:
+
+.. attribute:: FilePathField.path
+
+    Required. The absolute filesystem path to a directory from which this
+    :class:`FilePathField` should get its choices. Example: ``"/home/images"``.
+
+.. attribute:: FilePathField.match
+
+    Optional. A regular expression, as a string, that :class:`FilePathField`
+    will use to filter filenames. Note that the regex will be applied to the
+    base filename, not the full path. Example: ``"foo.*\.txt$"``, which will
+    match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
+
+.. attribute:: FilePathField.recursive
+
+    Optional. Either ``True`` or ``False``. Default is ``False``. Specifies
+    whether all subdirectories of :attr:`~FilePathField.path` should be included
+
+Of course, these arguments can be used together.
+
+The one potential gotcha is that :attr:`~FilePathField.match` applies to the
+base filename, not the full path. So, this example::
+
+    FilePathField(path="/home/images", match="foo.*", recursive=True)
+
+...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
+because the :attr:`~FilePathField.match` applies to the base filename
+(``foo.gif`` and ``bar.gif``).
+
+.. versionadded:: 1.0
+   The ``max_length`` argument was added in this version.
+
+By default, :class:`FilePathField` instances are
+created as ``varchar(100)`` columns in your database. As with other fields, you
+can change the maximum length using the :attr:`~CharField.max_length` argument.
+
+``FloatField``
+--------------
+
+.. class:: FloatField([**options])
+
+.. versionchanged:: 1.0
+
+A floating-point number represented in Python by a ``float`` instance.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+``ImageField``
+--------------
+
+.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options])
+
+Inherits all attributes and methods from :class:`FileField`, but also
+validates that the uploaded object is a valid image.
+
+In addition to the special attributes that are available for :class:`FileField`,
+an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
+:attr:`~django.core.files.File.width` attributes.
+
+To facilitate querying on those attributes, :class:`ImageField` has two extra
+optional arguments:
+
+.. attribute:: ImageField.height_field
+
+    Name of a model field which will be auto-populated with the height of the
+    image each time the model instance is saved.
+
+.. attribute:: ImageField.width_field
+
+    Name of a model field which will be auto-populated with the width of the
+    image each time the model instance is saved.
+
+Requires the `Python Imaging Library`_.
+
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+
+.. versionadded:: 1.0
+   The ``max_length`` argument was added in this version.
+
+By default, :class:`ImageField` instances are created as ``varchar(100)``
+columns in your database. As with other fields, you can change the maximum
+length using the :attr:`~CharField.max_length` argument.
+
+``IntegerField``
+----------------
+
+.. class:: IntegerField([**options])
+
+An integer. The admin represents this as an ``<input type="text">`` (a
+single-line input).
+
+``IPAddressField``
+------------------
+
+.. class:: IPAddressField([**options])
+
+An IP address, in string format (e.g. "192.0.2.30"). The admin represents this
+as an ``<input type="text">`` (a single-line input).
+
+``NullBooleanField``
+--------------------
+
+.. class:: NullBooleanField([**options])
+
+Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use
+this instead of a :class:`BooleanField` with ``null=True``. The admin represents
+this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
+
+``PositiveIntegerField``
+------------------------
+
+.. class:: PositiveIntegerField([**options])
+
+Like an :class:`IntegerField`, but must be positive.
+
+``PositiveSmallIntegerField``
+-----------------------------
+
+.. class:: PositiveSmallIntegerField([**options])
+
+Like a :class:`PositiveIntegerField`, but only allows values under a certain
+(database-dependent) point.
+
+``SlugField``
+-------------
+
+.. class:: SlugField([max_length=50, **options])
+
+:term:`Slug` is a newspaper term. A slug is a short label for something,
+containing only letters, numbers, underscores or hyphens. They're generally used
+in URLs.
+
+Like a CharField, you can specify :attr:`~CharField.max_length` (read the note
+about database portability and :attr:`~CharField.max_length` in that section,
+too). If :attr:`~CharField.max_length` is not specified, Django will use a
+default length of 50.
+
+Implies setting :attr:`Field.db_index` to ``True``.
+
+It is often useful to automatically prepopulate a SlugField based on the value
+of some other value.  You can do this automatically in the admin using
+:attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`.
+
+``SmallIntegerField``
+---------------------
+
+.. class:: SmallIntegerField([**options])
+
+Like an :class:`IntegerField`, but only allows values under a certain
+(database-dependent) point.
+
+``TextField``
+-------------
+
+.. class:: TextField([**options])
+
+A large text field. The admin represents this as a ``<textarea>`` (a multi-line
+input).
+
+.. admonition:: MySQL users
+
+    If you are using this field with MySQLdb 1.2.1p2 and the ``utf8_bin``
+    collation (which is *not* the default), there are some issues to be aware
+    of. Refer to the :ref:`MySQL database notes <mysql-collation>` for
+    details.
+
+``TimeField``
+-------------
+
+.. class:: TimeField([auto_now=False, auto_now_add=False, **options])
+
+A time, represented in Python by a ``datetime.time`` instance. Accepts the same
+auto-population options as :class:`DateField`.
+
+The admin represents this as an ``<input type="text">`` with some JavaScript
+shortcuts.
+
+``URLField``
+------------
+
+.. class:: URLField([verify_exists=True, max_length=200, **options])
+
+A :class:`CharField` for a URL. Has one extra optional argument:
+
+.. attribute:: URLField.verify_exists
+
+    If ``True`` (the default), the URL given will be checked for existence
+    (i.e., the URL actually loads and doesn't give a 404 response).
+
+    Note that when you're using the single-threaded development server,
+    validating a URL being served by the same server will hang. This should not
+    be a problem for multithreaded servers.
+
+The admin represents this as an ``<input type="text">`` (a single-line input).
+
+Like all :class:`CharField` subclasses, :class:`URLField` takes the optional
+:attr:`~CharField.max_length`argument. If you don't specify
+:attr:`~CharField.max_length`, a default of 200 is used.
+
+``XMLField``
+------------
+
+.. class:: XMLField(schema_path=None, [**options])
+
+A :class:`TextField` that checks that the value is valid XML that matches a
+given schema. Takes one required argument:
+
+.. attribute:: schema_path
+
+    The filesystem path to a RelaxNG_ schema against which to validate the
+    field.
+
+.. _RelaxNG: http://www.relaxng.org/
+
+Relationship fields
+===================
+
+.. module:: django.db.models.fields.related
+   :synopsis: Related field types
+
+.. currentmodule:: django.db.models
+
+Django also defines a set of fields that represent relations.
+
+.. _ref-foreignkey:
+
+``ForeignKey``
+--------------
+
+.. class:: ForeignKey(othermodel, [**options])
+
+A many-to-one relationship. Requires a positional argument: the class to which
+the model is related.
+
+.. _recursive-relationships:
+
+To create a recursive relationship -- an object that has a many-to-one
+relationship with itself -- use ``models.ForeignKey('self')``.
+
+.. _lazy-relationships:
+
+If you need to create a relationship on a model that has not yet been defined,
+you can use the name of the model, rather than the model object itself::
+
+    class Car(models.Model):
+        manufacturer = models.ForeignKey('Manufacturer')
+        # ...
+
+    class Manufacturer(models.Model):
+        # ...
+
+.. versionadded:: 1.0
+
+To refer to models defined in another application, you can explicitly specify
+a model with the full application label. For example, if the ``Manufacturer``
+model above is defined in another application called ``production``, you'd
+need to use::
+
+    class Car(models.Model):
+        manufacturer = models.ForeignKey('production.Manufacturer')
+
+This sort of reference can be useful when resolving circular import
+dependencies between two applications.
+
+Database Representation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Behind the scenes, Django appends ``"_id"`` to the field name to create its
+database column name. In the above example, the database table for the ``Car``
+model will have a ``manufacturer_id`` column. (You can change this explicitly by
+specifying :attr:`~Field.db_column`) However, your code should never have to
+deal with the database column name, unless you write custom SQL. You'll always
+deal with the field names of your model object.
+
+.. _foreign-key-arguments:
+
+Arguments
+~~~~~~~~~
+
+:class:`ForeignKey` accepts an extra set of arguments -- all optional -- that
+define the details of how the relation works.
+
+.. attribute:: ForeignKey.limit_choices_to
+
+    A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`)
+    that limit the available admin choices for this object. Use this with
+    functions from the Python ``datetime`` module to limit choices of objects by
+    date. For example::
+
+        limit_choices_to = {'pub_date__lte': datetime.now}
+
+    only allows the choice of related objects with a ``pub_date`` before the
+    current date/time to be chosen.
+
+    Instead of a dictionary this can also be a :class:`~django.db.models.Q`
+    object for more :ref:`complex queries <complex-lookups-with-q>`. However,
+    if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it
+    will only have an effect on the choices available in the admin when the
+    field is not listed in ``raw_id_fields`` in the ``ModelAdmin`` for the model.
+
+.. attribute:: ForeignKey.related_name
+
+    The name to use for the relation from the related object back to this one.
+    See the :ref:`related objects documentation <backwards-related-objects>` for
+    a full explanation and example. Note that you must set this value
+    when defining relations on :ref:`abstract models
+    <abstract-base-classes>`; and when you do so
+    :ref:`some special syntax <abstract-related-name>` is available.
+
+    If you wish to suppress the provision of a backwards relation, you may
+    simply provide a ``related_name`` which ends with a ``'+'`` character.
+    For example::
+   
+        user = models.ForeignKey(User, related_name='+')
+
+    will ensure that no backwards relation to this model is provided on the 
+    ``User`` model.
+
+.. attribute:: ForeignKey.to_field
+
+    The field on the related object that the relation is to. By default, Django
+    uses the primary key of the related object.
+
+.. _ref-manytomany:
+
+``ManyToManyField``
+-------------------
+
+.. class:: ManyToManyField(othermodel, [**options])
+
+A many-to-many relationship. Requires a positional argument: the class to which
+the model is related. This works exactly the same as it does for
+:class:`ForeignKey`, including all the options regarding :ref:`recursive
+<recursive-relationships>` and :ref:`lazy <lazy-relationships>` relationships.
+
+Database Representation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Behind the scenes, Django creates an intermediary join table to
+represent the many-to-many relationship. By default, this table name
+is generated using the name of the many-to-many field and the model
+that contains it. Since some databases don't support table names above
+a certain length, these table names will be automatically truncated to
+64 characters and a uniqueness hash will be used. This means you might
+see table names like ``author_books_9cdf4``; this is perfectly normal.
+You can manually provide the name of the join table using the
+:attr:`~ManyToManyField.db_table` option.
+
+.. _manytomany-arguments:
+
+Arguments
+~~~~~~~~~
+
+:class:`ManyToManyField` accepts an extra set of arguments -- all optional --
+that control how the relationship functions.
+
+.. attribute:: ManyToManyField.related_name
+
+    Same as :attr:`ForeignKey.related_name`.
+
+.. attribute:: ManyToManyField.limit_choices_to
+
+    Same as :attr:`ForeignKey.limit_choices_to`.
+
+    ``limit_choices_to`` has no effect when used on a ``ManyToManyField`` with a
+    custom intermediate table specified using the
+    :attr:`~ManyToManyField.through` parameter.
+
+.. attribute:: ManyToManyField.symmetrical
+
+    Only used in the definition of ManyToManyFields on self. Consider the
+    following model::
+
+        class Person(models.Model):
+            friends = models.ManyToManyField("self")
+
+    When Django processes this model, it identifies that it has a
+    :class:`ManyToManyField` on itself, and as a result, it doesn't add a
+    ``person_set`` attribute to the ``Person`` class. Instead, the
+    :class:`ManyToManyField` is assumed to be symmetrical -- that is, if I am
+    your friend, then you are my friend.
+
+    If you do not want symmetry in many-to-many relationships with ``self``, set
+    :attr:`~ManyToManyField.symmetrical` to ``False``. This will force Django to
+    add the descriptor for the reverse relationship, allowing
+    :class:`ManyToManyField` relationships to be non-symmetrical.
+
+.. attribute:: ManyToManyField.through
+
+    Django will automatically generate a table to manage many-to-many
+    relationships. However, if you want to manually specify the intermediary
+    table, you can use the :attr:`~ManyToManyField.through` option to specify
+    the Django model that represents the intermediate table that you want to
+    use.
+
+    The most common use for this option is when you want to associate
+    :ref:`extra data with a many-to-many relationship
+    <intermediary-manytomany>`.
+
+.. attribute:: ManyToManyField.db_table
+
+    The name of the table to create for storing the many-to-many data. If this
+    is not provided, Django will assume a default name based upon the names of
+    the two tables being joined.
+
+.. _ref-onetoone:
+
+``OneToOneField``
+-----------------
+
+.. class:: OneToOneField(othermodel, [parent_link=False, **options])
+
+A one-to-one relationship. Conceptually, this is similar to a
+:class:`ForeignKey` with :attr:`unique=True <Field.unique>`, but the
+"reverse" side of the relation will directly return a single object.
+
+This is most useful as the primary key of a model which "extends"
+another model in some way; :ref:`multi-table-inheritance` is
+implemented by adding an implicit one-to-one relation from the child
+model to the parent model, for example.
+
+One positional argument is required: the class to which the model will be
+related. This works exactly the same as it does for :class:`ForeignKey`,
+including all the options regarding :ref:`recursive <recursive-relationships>`
+and :ref:`lazy <lazy-relationships>` relationships.
+
+.. _onetoone-arguments:
+
+Additionally, ``OneToOneField`` accepts all of the extra arguments
+accepted by :class:`ForeignKey`, plus one extra argument:
+
+.. attribute:: OneToOneField.parent_link
+
+    When ``True`` and used in a model which inherits from another
+    (concrete) model, indicates that this field should be used as the
+    link back to the parent class, rather than the extra
+    ``OneToOneField`` which would normally be implicitly created by
+    subclassing.
diff --git a/parts/django/docs/ref/models/index.txt b/parts/django/docs/ref/models/index.txt
new file mode 100644
index 0000000..b5896c3
--- /dev/null
+++ b/parts/django/docs/ref/models/index.txt
@@ -0,0 +1,14 @@
+======
+Models
+======
+
+Model API reference. For introductory material, see :doc:`/topics/db/models`.
+
+.. toctree::
+   :maxdepth: 1
+
+   fields
+   relations
+   options
+   instances
+   querysets
diff --git a/parts/django/docs/ref/models/instances.txt b/parts/django/docs/ref/models/instances.txt
new file mode 100644
index 0000000..1730ec6
--- /dev/null
+++ b/parts/django/docs/ref/models/instances.txt
@@ -0,0 +1,570 @@
+========================
+Model instance reference
+========================
+
+.. currentmodule:: django.db.models
+
+This document describes the details of the ``Model`` API. It builds on the
+material presented in the :doc:`model </topics/db/models>` and :doc:`database
+query </topics/db/queries>` guides, so you'll probably want to read and
+understand those documents before reading this one.
+
+Throughout this reference we'll use the :ref:`example Weblog models
+<queryset-model-example>` presented in the :doc:`database query guide
+</topics/db/queries>`.
+
+Creating objects
+================
+
+To create a new instance of a model, just instantiate it like any other Python
+class:
+
+.. class:: Model(**kwargs)
+
+The keyword arguments are simply the names of the fields you've defined on your
+model. Note that instantiating a model in no way touches your database; for
+that, you need to ``save()``.
+
+.. _validating-objects:
+
+Validating objects
+==================
+
+.. versionadded:: 1.2
+
+There are three steps involved in validating a model:
+
+    1. Validate the model fields
+    2. Validate the model as a whole
+    3. Validate the field uniqueness
+
+All three steps are performed when you call by a model's
+``full_clean()`` method.
+
+When you use a ``ModelForm``, the call to ``is_valid()`` will perform
+these validation steps for all the fields that are included on the
+form. (See the :doc:`ModelForm documentation
+</topics/forms/modelforms>` for more information.) You should only need
+to call a model's ``full_clean()`` method if you plan to handle
+validation errors yourself, or if you have excluded fields from the
+ModelForm that require validation.
+
+.. method:: Model.full_clean(exclude=None)
+
+This method calls ``Model.clean_fields()``, ``Model.clean()``, and
+``Model.validate_unique()``, in that order and raises a ``ValidationError``
+that has a ``message_dict`` attribute containing errors from all three stages.
+
+The optional ``exclude`` argument can be used to provide a list of field names
+that can be excluded from validation and cleaning. ``ModelForm`` uses this
+argument to exclude fields that aren't present on your form from being
+validated since any errors raised could not be corrected by the user.
+
+Note that ``full_clean()`` will *not* be called automatically when you
+call your model's ``save()`` method, nor as a result of ``ModelForm``
+validation. You'll need to call it manually when you want to run model
+validation outside of a ``ModelForm``.
+
+Example::
+
+    try:
+        article.full_clean()
+    except ValidationError, e:
+        # Do something based on the errors contained in e.message_dict.
+        # Display them to a user, or handle them programatically.
+
+The first step ``full_clean()`` performs is to clean each individual field.
+
+.. method:: Model.clean_fields(exclude=None)
+
+This method will validate all fields on your model. The optional ``exclude``
+argument lets you provide a list of field names to exclude from validation. It
+will raise a ``ValidationError`` if any fields fail validation.
+
+The second step ``full_clean()`` performs is to call ``Model.clean()``.
+This method should be overridden to perform custom validation on your model.
+
+.. method:: Model.clean()
+
+This method should be used to provide custom model validation, and to modify
+attributes on your model if desired. For instance, you could use it to
+automatically provide a value for a field, or to do validation that requires
+access to more than a single field::
+
+    def clean(self):
+        from django.core.exceptions import ValidationError
+        # Don't allow draft entries to have a pub_date.
+        if self.status == 'draft' and self.pub_date is not None:
+            raise ValidationError('Draft entries may not have a publication date.')
+        # Set the pub_date for published items if it hasn't been set already.
+        if self.status == 'published' and self.pub_date is None:
+            self.pub_date = datetime.datetime.now()
+
+Any ``ValidationError`` raised by ``Model.clean()`` will be stored under a
+special key that is used for errors that are tied to the entire model instead
+of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``::
+
+
+    from django.core.exceptions import ValidationError, NON_FIELD_ERRORS
+    try:
+        article.full_clean()
+    except ValidationError, e:
+        non_field_errors = e.message_dict[NON_FIELD_ERRORS]
+
+Finally, ``full_clean()`` will check any unique constraints on your model.
+
+.. method:: Model.validate_unique(exclude=None)
+
+This method is similar to ``clean_fields``, but validates all uniqueness
+constraints on your model instead of individual field values. The optional
+``exclude`` argument allows you to provide a list of field names to exclude
+from validation. It will raise a ``ValidationError`` if any fields fail
+validation.
+
+Note that if you provide an ``exclude`` argument to ``validate_unique``, any
+``unique_together`` constraint that contains one of the fields you provided
+will not be checked.
+
+
+Saving objects
+==============
+
+To save an object back to the database, call ``save()``:
+
+.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS])
+
+.. versionadded:: 1.0
+   The ``force_insert`` and ``force_update`` arguments were added.
+
+.. versionadded:: 1.2
+   The ``using`` argument was added.
+
+If you want customized saving behavior, you can override this
+``save()`` method. See :ref:`overriding-model-methods` for more
+details.
+
+The model save process also has some subtleties; see the sections
+below.
+
+Auto-incrementing primary keys
+------------------------------
+
+If a model has an ``AutoField`` -- an auto-incrementing primary key -- then
+that auto-incremented value will be calculated and saved as an attribute on
+your object the first time you call ``save()``::
+
+    >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
+    >>> b2.id     # Returns None, because b doesn't have an ID yet.
+    >>> b2.save()
+    >>> b2.id     # Returns the ID of your new object.
+
+There's no way to tell what the value of an ID will be before you call
+``save()``, because that value is calculated by your database, not by Django.
+
+(For convenience, each model has an ``AutoField`` named ``id`` by default
+unless you explicitly specify ``primary_key=True`` on a field. See the
+documentation for ``AutoField`` for more details.
+
+The ``pk`` property
+~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+.. attribute:: Model.pk
+
+Regardless of whether you define a primary key field yourself, or let Django
+supply one for you, each model will have a property called ``pk``. It behaves
+like a normal attribute on the model, but is actually an alias for whichever
+attribute is the primary key field for the model. You can read and set this
+value, just as you would for any other attribute, and it will update the
+correct field in the model.
+
+Explicitly specifying auto-primary-key values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a model has an ``AutoField`` but you want to define a new object's ID
+explicitly when saving, just define it explicitly before saving, rather than
+relying on the auto-assignment of the ID::
+
+    >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
+    >>> b3.id     # Returns 3.
+    >>> b3.save()
+    >>> b3.id     # Returns 3.
+
+If you assign auto-primary-key values manually, make sure not to use an
+already-existing primary-key value! If you create a new object with an explicit
+primary-key value that already exists in the database, Django will assume you're
+changing the existing record rather than creating a new one.
+
+Given the above ``'Cheddar Talk'`` blog example, this example would override the
+previous record in the database::
+
+    b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
+    b4.save()  # Overrides the previous blog with ID=3!
+
+See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this
+happens.
+
+Explicitly specifying auto-primary-key values is mostly useful for bulk-saving
+objects, when you're confident you won't have primary-key collision.
+
+What happens when you save?
+---------------------------
+
+When you save an object, Django performs the following steps:
+
+    1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>`
+       :attr:`django.db.models.signals.pre_save` is sent, allowing any
+       functions listening for that signal to take some customized
+       action.
+
+    2. **Pre-process the data.** Each field on the object is asked to
+       perform any automated data modification that the field may need
+       to perform.
+
+       Most fields do *no* pre-processing -- the field data is kept as-is.
+       Pre-processing is only used on fields that have special behavior.
+       For example, if your model has a ``DateField`` with ``auto_now=True``,
+       the pre-save phase will alter the data in the object to ensure that
+       the date field contains the current date stamp. (Our documentation
+       doesn't yet include a list of all the fields with this "special
+       behavior.")
+
+    3. **Prepare the data for the database.** Each field is asked to provide
+       its current value in a data type that can be written to the database.
+
+       Most fields require *no* data preparation. Simple data types, such as
+       integers and strings, are 'ready to write' as a Python object. However,
+       more complex data types often require some modification.
+
+       For example, ``DateFields`` use a Python ``datetime`` object to store
+       data. Databases don't store ``datetime`` objects, so the field value
+       must be converted into an ISO-compliant date string for insertion
+       into the database.
+
+    4. **Insert the data into the database.** The pre-processed, prepared
+       data is then composed into an SQL statement for insertion into the
+       database.
+
+    5. **Emit a post-save signal.** The signal
+       :attr:`django.db.models.signals.post_save` is sent, allowing
+       any functions listening for that signal to take some customized
+       action.
+
+How Django knows to UPDATE vs. INSERT
+-------------------------------------
+
+You may have noticed Django database objects use the same ``save()`` method
+for creating and changing objects. Django abstracts the need to use ``INSERT``
+or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django
+follows this algorithm:
+
+    * If the object's primary key attribute is set to a value that evaluates to
+      ``True`` (i.e., a value other than ``None`` or the empty string), Django
+      executes a ``SELECT`` query to determine whether a record with the given
+      primary key already exists.
+    * If the record with the given primary key does already exist, Django
+      executes an ``UPDATE`` query.
+    * If the object's primary key attribute is *not* set, or if it's set but a
+      record doesn't exist, Django executes an ``INSERT``.
+
+The one gotcha here is that you should be careful not to specify a primary-key
+value explicitly when saving new objects, if you cannot guarantee the
+primary-key value is unused. For more on this nuance, see `Explicitly specifying
+auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below.
+
+.. _ref-models-force-insert:
+
+Forcing an INSERT or UPDATE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+In some rare circumstances, it's necessary to be able to force the ``save()``
+method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``.
+Or vice-versa: update, if possible, but not insert a new row. In these cases
+you can pass the ``force_insert=True`` or ``force_update=True`` parameters to
+the ``save()`` method. Passing both parameters is an error, since you cannot
+both insert *and* update at the same time.
+
+It should be very rare that you'll need to use these parameters. Django will
+almost always do the right thing and trying to override that will lead to
+errors that are difficult to track down. This feature is for advanced use
+only.
+
+Updating attributes based on existing fields
+--------------------------------------------
+
+Sometimes you'll need to perform a simple arithmetic task on a field, such
+as incrementing or decrementing the current value. The obvious way to
+achieve this is to do something like::
+
+    >>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
+    >>> product.number_sold += 1
+    >>> product.save()
+
+If the old ``number_sold`` value retrieved from the database was 10, then
+the value of 11 will be written back to the database.
+
+This can be optimized slightly by expressing the update relative to the
+original field value, rather than as an explicit assignment of a new value.
+Django provides :ref:`F() expressions <query-expressions>` as a way of
+performing this kind of relative update. Using ``F()`` expressions, the
+previous example would be expressed as::
+
+    >>> from django.db.models import F
+    >>> product = Product.objects.get(name='Venezuelan Beaver Cheese')
+    >>> product.number_sold = F('number_sold') + 1
+    >>> product.save()
+
+This approach doesn't use the initial value from the database. Instead, it
+makes the database do the update based on whatever value is current at the
+time that the save() is executed.
+
+Once the object has been saved, you must reload the object in order to access
+the actual value that was applied to the updated field::
+
+    >>> product = Products.objects.get(pk=product.pk)
+    >>> print product.number_sold
+    42
+
+For more details, see the documentation on :ref:`F() expressions
+<query-expressions>` and their :ref:`use in update queries
+<topics-db-queries-update>`.
+
+Deleting objects
+================
+
+.. method:: Model.delete([using=DEFAULT_DB_ALIAS])
+
+.. versionadded:: 1.2
+   The ``using`` argument was added.
+
+Issues a SQL ``DELETE`` for the object. This only deletes the object
+in the database; the Python instance will still be around, and will
+still have data in its fields.
+
+For more details, including how to delete objects in bulk, see
+:ref:`topics-db-queries-delete`.
+
+If you want customized deletion behavior, you can override this
+``delete()`` method. See :ref:`overriding-model-methods` for more
+details.
+
+.. _model-instance-methods:
+
+Other model instance methods
+============================
+
+A few object methods have special purposes.
+
+``__str__``
+-----------
+
+.. method:: Model.__str__()
+
+``__str__()`` is a Python "magic method" that defines what should be returned
+if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related
+function, ``unicode(obj)`` -- see below) in a number of places, most notably
+as the value displayed to render an object in the Django admin site and as the
+value inserted into a template when it displays an object. Thus, you should
+always return a nice, human-readable string for the object's ``__str__``.
+Although this isn't required, it's strongly encouraged (see the description of
+``__unicode__``, below, before putting ``__str__`` methods everywhere).
+
+For example::
+
+    class Person(models.Model):
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+
+        def __str__(self):
+            # Note use of django.utils.encoding.smart_str() here because
+            # first_name and last_name will be unicode strings.
+            return smart_str('%s %s' % (self.first_name, self.last_name))
+
+``__unicode__``
+---------------
+
+.. method:: Model.__unicode__()
+
+The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
+object. Since Django's database backends will return Unicode strings in your
+model's attributes, you would normally want to write a ``__unicode__()``
+method for your model. The example in the previous section could be written
+more simply as::
+
+    class Person(models.Model):
+        first_name = models.CharField(max_length=50)
+        last_name = models.CharField(max_length=50)
+
+        def __unicode__(self):
+            return u'%s %s' % (self.first_name, self.last_name)
+
+If you define a ``__unicode__()`` method on your model and not a ``__str__()``
+method, Django will automatically provide you with a ``__str__()`` that calls
+``__unicode__()`` and then converts the result correctly to a UTF-8 encoded
+string object. This is recommended development practice: define only
+``__unicode__()`` and let Django take care of the conversion to string objects
+when required.
+
+``get_absolute_url``
+--------------------
+
+.. method:: Model.get_absolute_url()
+
+Define a ``get_absolute_url()`` method to tell Django how to calculate the
+URL for an object. For example::
+
+    def get_absolute_url(self):
+        return "/people/%i/" % self.id
+
+Django uses this in its admin interface. If an object defines
+``get_absolute_url()``, the object-editing page will have a "View on site"
+link that will jump you directly to the object's public view, according to
+``get_absolute_url()``.
+
+Also, a couple of other bits of Django, such as the :doc:`syndication feed
+framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a
+convenience to reward people who've defined the method.
+
+It's good practice to use ``get_absolute_url()`` in templates, instead of
+hard-coding your objects' URLs. For example, this template code is bad::
+
+    <a href="/people/{{ object.id }}/">{{ object.name }}</a>
+
+But this template code is good::
+
+    <a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
+
+.. note::
+    The string you return from ``get_absolute_url()`` must contain only ASCII
+    characters (required by the URI spec, `RFC 2396`_) that have been
+    URL-encoded, if necessary. Code and templates using ``get_absolute_url()``
+    should be able to use the result directly without needing to do any
+    further processing. You may wish to use the
+    ``django.utils.encoding.iri_to_uri()`` function to help with this if you
+    are using unicode strings a lot.
+
+.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt
+
+The ``permalink`` decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The problem with the way we wrote ``get_absolute_url()`` above is that it
+slightly violates the DRY principle: the URL for this object is defined both
+in the URLconf file and in the model.
+
+You can further decouple your models from the URLconf using the ``permalink``
+decorator:
+
+.. function:: permalink()
+
+This decorator is passed the view function, a list of positional parameters and
+(optionally) a dictionary of named parameters. Django then works out the correct
+full URL path using the URLconf, substituting the parameters you have given into
+the URL. For example, if your URLconf contained a line such as::
+
+    (r'^people/(\d+)/$', 'people.views.details'),
+
+...your model could have a ``get_absolute_url`` method that looked like this::
+
+    from django.db import models
+
+    @models.permalink
+    def get_absolute_url(self):
+        return ('people.views.details', [str(self.id)])
+
+Similarly, if you had a URLconf entry that looked like::
+
+    (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view)
+
+...you could reference this using ``permalink()`` as follows::
+
+    @models.permalink
+    def get_absolute_url(self):
+        return ('archive_view', (), {
+            'year': self.created.year,
+            'month': self.created.month,
+            'day': self.created.day})
+
+Notice that we specify an empty sequence for the second parameter in this case,
+because we only want to pass keyword parameters, not positional ones.
+
+In this way, you're tying the model's absolute path to the view that is used
+to display it, without repeating the URL information anywhere. You can still
+use the ``get_absolute_url`` method in templates, as before.
+
+In some cases, such as the use of generic views or the re-use of
+custom views for multiple models, specifying the view function may
+confuse the reverse URL matcher (because multiple patterns point to
+the same view).
+
+For that problem, Django has **named URL patterns**. Using a named
+URL pattern, it's possible to give a name to a pattern, and then
+reference the name rather than the view function. A named URL
+pattern is defined by replacing the pattern tuple by a call to
+the ``url`` function)::
+
+    from django.conf.urls.defaults import *
+
+    url(r'^people/(\d+)/$',
+        'django.views.generic.list_detail.object_detail',
+        name='people_view'),
+
+...and then using that name to perform the reverse URL resolution instead
+of the view name::
+
+    from django.db import models
+
+    @models.permalink
+    def get_absolute_url(self):
+        return ('people_view', [str(self.id)])
+
+More details on named URL patterns are in the :doc:`URL dispatch documentation
+</topics/http/urls>`.
+
+Extra instance methods
+======================
+
+In addition to ``save()``, ``delete()``, a model object might get any or all
+of the following methods:
+
+.. method:: Model.get_FOO_display()
+
+For every field that has ``choices`` set, the object will have a
+``get_FOO_display()`` method, where ``FOO`` is the name of the field. This
+method returns the "human-readable" value of the field. For example, in the
+following model::
+
+    GENDER_CHOICES = (
+        ('M', 'Male'),
+        ('F', 'Female'),
+    )
+    class Person(models.Model):
+        name = models.CharField(max_length=20)
+        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+
+...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
+
+    >>> p = Person(name='John', gender='M')
+    >>> p.save()
+    >>> p.gender
+    'M'
+    >>> p.get_gender_display()
+    'Male'
+
+.. method:: Model.get_next_by_FOO(\**kwargs)
+.. method:: Model.get_previous_by_FOO(\**kwargs)
+
+For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``,
+the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()``
+methods, where ``FOO`` is the name of the field. This returns the next and
+previous object with respect to the date field, raising the appropriate
+``DoesNotExist`` exception when appropriate.
+
+Both methods accept optional keyword arguments, which should be in the format
+described in :ref:`Field lookups <field-lookups>`.
+
+Note that in the case of identical date values, these methods will use the ID
+as a fallback check. This guarantees that no records are skipped or duplicated.
diff --git a/parts/django/docs/ref/models/options.txt b/parts/django/docs/ref/models/options.txt
new file mode 100644
index 0000000..1b04c46
--- /dev/null
+++ b/parts/django/docs/ref/models/options.txt
@@ -0,0 +1,269 @@
+======================
+Model ``Meta`` options
+======================
+
+This document explains all the possible :ref:`metadata options
+<meta-options>` that you can give your model in its internal ``class
+Meta``.
+
+Available ``Meta`` options
+==========================
+
+.. currentmodule:: django.db.models
+
+``abstract``
+------------
+
+.. attribute:: Options.abstract
+
+If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`.
+
+``app_label``
+-------------
+
+.. attribute:: Options.app_label
+
+If a model exists outside of the standard :file:`models.py` (for instance, if
+the app's models are in submodules of ``myapp.models``), the model must define
+which app it is part of::
+
+    app_label = 'myapp'
+
+``db_table``
+------------
+
+.. attribute:: Options.db_table
+
+The name of the database table to use for the model::
+
+    db_table = 'music_album'
+
+.. _table-names:
+
+Table names
+~~~~~~~~~~~
+
+To save you time, Django automatically derives the name of the database table
+from the name of your model class and the app that contains it. A model's
+database table name is constructed by joining the model's "app label" -- the
+name you used in ``manage.py startapp`` -- to the model's class name, with an
+underscore between them.
+
+For example, if you have an app ``bookstore`` (as created by
+``manage.py startapp bookstore``), a model defined as ``class Book`` will have
+a database table named ``bookstore_book``.
+
+To override the database table name, use the ``db_table`` parameter in
+``class Meta``.
+
+If your database table name is an SQL reserved word, or contains characters that
+aren't allowed in Python variable names -- notably, the hyphen -- that's OK.
+Django quotes column and table names behind the scenes.
+
+``db_tablespace``
+-----------------
+
+.. attribute:: Options.db_tablespace
+
+.. versionadded:: 1.0
+
+The name of the database tablespace to use for the model. If the backend doesn't
+support tablespaces, this option is ignored.
+
+``get_latest_by``
+-----------------
+
+.. attribute:: Options.get_latest_by
+
+The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
+specifies the default field to use in your model :class:`Manager`'s
+:class:`~QuerySet.latest` method.
+
+Example::
+
+    get_latest_by = "order_date"
+
+See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
+
+``managed``
+-----------------------
+
+.. attribute:: Options.managed
+
+.. versionadded:: 1.1
+
+Defaults to ``True``, meaning Django will create the appropriate database
+tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
+management command. That is, Django *manages* the database tables' lifecycles.
+
+If ``False``, no database table creation or deletion operations will be
+performed for this model. This is useful if the model represents an existing
+table or a database view that has been created by some other means. This is
+the *only* difference when ``managed`` is ``False``. All other aspects of
+model handling are exactly the same as normal. This includes
+
+    1. Adding an automatic primary key field to the model if you don't declare
+       it.  To avoid confusion for later code readers, it's recommended to
+       specify all the columns from the database table you are modeling when
+       using unmanaged models.
+
+    2. If a model with ``managed=False`` contains a
+       :class:`~django.db.models.ManyToManyField` that points to another
+       unmanaged model, then the intermediate table for the many-to-many join
+       will also not be created. However, a the intermediary table between one
+       managed and one unmanaged model *will* be created.
+
+       If you need to change this default behavior, create the intermediary
+       table as an explicit model (with ``managed`` set as needed) and use the
+       :attr:`ManyToManyField.through` attribute to make the relation use your
+       custom model.
+
+For tests involving models with ``managed=False``, it's up to you to ensure
+the correct tables are created as part of the test setup.
+
+If you're interested in changing the Python-level behavior of a model class,
+you *could* use ``managed=False`` and create a copy of an existing model.
+However, there's a better approach for that situation: :ref:`proxy-models`.
+
+``order_with_respect_to``
+-------------------------
+
+.. attribute:: Options.order_with_respect_to
+
+Marks this object as "orderable" with respect to the given field. This is almost
+always used with related objects to allow them to be ordered with respect to a
+parent object. For example, if an ``Answer`` relates to a ``Question`` object,
+and a question has more than one answer, and the order of answers matters, you'd
+do this::
+
+    class Answer(models.Model):
+        question = models.ForeignKey(Question)
+        # ...
+
+        class Meta:
+            order_with_respect_to = 'question'
+
+When ``order_with_respect_to`` is set, two additional methods are provided to
+retrieve and to set the order of the related objects: ``get_RELATED_order()``
+and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For
+example, assuming that a ``Question`` object has multiple related ``Answer``
+objects, the list returned contains the primary keys of the related ``Answer``
+objects::
+
+    >>> question = Question.objects.get(id=1)
+    >>> question.get_answer_order()
+    [1, 2, 3]
+
+The order of a ``Question`` object's related ``Answer`` objects can be set by
+passing in a list of ``Answer`` primary keys::
+
+    >>> question.set_answer_order([3, 1, 2])
+
+The related objects also get two methods, ``get_next_in_order()`` and
+``get_previous_in_order()``, which can be used to access those objects in their
+proper order. Assuming the ``Answer`` objects are ordered by ``id``::
+
+    >>> answer = Answer.objects.get(id=2)
+    >>> answer.get_next_in_order()
+    <Answer: 3>
+    >>> answer.get_previous_in_order()
+    <Answer: 1>
+
+``ordering``
+------------
+
+.. attribute:: Options.ordering
+
+The default ordering for the object, for use when obtaining lists of objects::
+
+    ordering = ['-order_date']
+
+This is a tuple or list of strings. Each string is a field name with an optional
+"-" prefix, which indicates descending order. Fields without a leading "-" will
+be ordered ascending. Use the string "?" to order randomly.
+
+.. note::
+
+    Regardless of how many fields are in :attr:`~Options.ordering`, the admin
+    site uses only the first field.
+
+For example, to order by a ``pub_date`` field ascending, use this::
+
+    ordering = ['pub_date']
+
+To order by ``pub_date`` descending, use this::
+
+    ordering = ['-pub_date']
+
+To order by ``pub_date`` descending, then by ``author`` ascending, use this::
+
+    ordering = ['-pub_date', 'author']
+
+``permissions``
+---------------
+
+.. attribute:: Options.permissions
+
+Extra permissions to enter into the permissions table when creating this object.
+Add, delete and change permissions are automatically created for each object
+that has ``admin`` set. This example specifies an extra permission,
+``can_deliver_pizzas``::
+
+    permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
+
+This is a list or tuple of 2-tuples in the format ``(permission_code,
+human_readable_permission_name)``.
+
+``proxy``
+---------
+
+.. attribute:: Options.proxy
+
+.. versionadded:: 1.1
+
+If set to ``True``, a model which subclasses another model will be treated as
+a :ref:`proxy model <proxy-models>`.
+
+``unique_together``
+-------------------
+
+.. attribute:: Options.unique_together
+
+Sets of field names that, taken together, must be unique::
+
+    unique_together = (("driver", "restaurant"),)
+
+This is a list of lists of fields that must be unique when considered together.
+It's used in the Django admin and is enforced at the database level (i.e., the
+appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
+statement).
+
+.. versionadded:: 1.0
+
+For convenience, unique_together can be a single list when dealing with a single
+set of fields::
+
+    unique_together = ("driver", "restaurant")
+
+``verbose_name``
+----------------
+
+.. attribute:: Options.verbose_name
+
+A human-readable name for the object, singular::
+
+    verbose_name = "pizza"
+
+If this isn't given, Django will use a munged version of the class name:
+``CamelCase`` becomes ``camel case``.
+
+``verbose_name_plural``
+-----------------------
+
+.. attribute:: Options.verbose_name_plural
+
+The plural name for the object::
+
+    verbose_name_plural = "stories"
+
+If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
diff --git a/parts/django/docs/ref/models/querysets.txt b/parts/django/docs/ref/models/querysets.txt
new file mode 100644
index 0000000..9f0de1f
--- /dev/null
+++ b/parts/django/docs/ref/models/querysets.txt
@@ -0,0 +1,1888 @@
+======================
+QuerySet API reference
+======================
+
+.. currentmodule:: django.db.models.QuerySet
+
+This document describes the details of the ``QuerySet`` API. It builds on the
+material presented in the :doc:`model </topics/db/models>` and :doc:`database
+query </topics/db/queries>` guides, so you'll probably want to read and
+understand those documents before reading this one.
+
+Throughout this reference we'll use the :ref:`example Weblog models
+<queryset-model-example>` presented in the :doc:`database query guide
+</topics/db/queries>`.
+
+.. _when-querysets-are-evaluated:
+
+When QuerySets are evaluated
+============================
+
+Internally, a ``QuerySet`` can be constructed, filtered, sliced, and generally
+passed around without actually hitting the database. No database activity
+actually occurs until you do something to evaluate the queryset.
+
+You can evaluate a ``QuerySet`` in the following ways:
+
+    * **Iteration.** A ``QuerySet`` is iterable, and it executes its database
+      query the first time you iterate over it. For example, this will print
+      the headline of all entries in the database::
+
+          for e in Entry.objects.all():
+              print e.headline
+
+    * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
+      be sliced, using Python's array-slicing syntax. Usually slicing a
+      ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will
+      execute the database query if you use the "step" parameter of slice
+      syntax.
+
+    * **Pickling/Caching.** See the following section for details of what
+      is involved when `pickling QuerySets`_. The important thing for the
+      purposes of this section is that the results are read from the database.
+
+    * **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
+      This is for convenience in the Python interactive interpreter, so you can
+      immediately see your results when using the API interactively.
+
+    * **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it.
+      This, as you might expect, returns the length of the result list.
+
+      Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is
+      determine the number of records in the set. It's much more efficient to
+      handle a count at the database level, using SQL's ``SELECT COUNT(*)``,
+      and Django provides a ``count()`` method for precisely this reason. See
+      ``count()`` below.
+
+    * **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on
+      it. For example::
+
+          entry_list = list(Entry.objects.all())
+
+      Be warned, though, that this could have a large memory overhead, because
+      Django will load each element of the list into memory. In contrast,
+      iterating over a ``QuerySet`` will take advantage of your database to
+      load data and instantiate objects only as you need them.
+
+    * **bool().** Testing a ``QuerySet`` in a boolean context, such as using
+      ``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query
+      to be executed. If there is at least one result, the ``QuerySet`` is
+      ``True``, otherwise ``False``. For example::
+
+          if Entry.objects.filter(headline="Test"):
+             print "There is at least one Entry with the headline Test"
+
+      Note: *Don't* use this if all you want to do is determine if at least one
+      result exists, and don't need the actual objects. It's more efficient to
+      use ``exists()`` (see below).
+
+.. _pickling QuerySets:
+
+Pickling QuerySets
+------------------
+
+If you pickle_ a ``QuerySet``, this will force all the results to be loaded
+into memory prior to pickling. Pickling is usually used as a precursor to
+caching and when the cached queryset is reloaded, you want the results to
+already be present and ready for use (reading from the database can take some
+time, defeating the purpose of caching). This means that when you unpickle a
+``QuerySet``, it contains the results at the moment it was pickled, rather
+than the results that are currently in the database.
+
+If you only want to pickle the necessary information to recreate the
+``QuerySet`` from the database at a later time, pickle the ``query`` attribute
+of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without
+any results loaded) using some code like this::
+
+    >>> import pickle
+    >>> query = pickle.loads(s)     # Assuming 's' is the pickled string.
+    >>> qs = MyModel.objects.all()
+    >>> qs.query = query            # Restore the original 'query'.
+
+The ``query`` attribute is an opaque object. It represents the internals of
+the query construction and is not part of the public API. However, it is safe
+(and fully supported) to pickle and unpickle the attribute's contents as
+described here.
+
+.. admonition:: You can't share pickles between versions
+
+	Pickles of QuerySets are only valid for the version of Django that
+	was used to generate them. If you generate a pickle using Django
+	version N, there is no guarantee that pickle will be readable with
+	Django version N+1. Pickles should not be used as part of a long-term
+	archival strategy.
+
+.. _pickle: http://docs.python.org/library/pickle.html
+
+.. _queryset-api:
+
+QuerySet API
+============
+
+Though you usually won't create one manually -- you'll go through a
+:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
+
+.. class:: QuerySet([model=None])
+
+Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
+filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
+
+Methods that return new QuerySets
+---------------------------------
+
+Django provides a range of ``QuerySet`` refinement methods that modify either
+the types of results returned by the ``QuerySet`` or the way its SQL query is
+executed.
+
+filter
+~~~~~~
+
+.. method:: filter(**kwargs)
+
+Returns a new ``QuerySet`` containing objects that match the given lookup
+parameters.
+
+The lookup parameters (``**kwargs``) should be in the format described in
+`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
+underlying SQL statement.
+
+exclude
+~~~~~~~
+
+.. method:: exclude(**kwargs)
+
+Returns a new ``QuerySet`` containing objects that do *not* match the given
+lookup parameters.
+
+The lookup parameters (``**kwargs``) should be in the format described in
+`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
+underlying SQL statement, and the whole thing is enclosed in a ``NOT()``.
+
+This example excludes all entries whose ``pub_date`` is later than 2005-1-3
+AND whose ``headline`` is "Hello"::
+
+    Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')
+
+In SQL terms, that evaluates to::
+
+    SELECT ...
+    WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')
+
+This example excludes all entries whose ``pub_date`` is later than 2005-1-3
+OR whose headline is "Hello"::
+
+    Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello')
+
+In SQL terms, that evaluates to::
+
+    SELECT ...
+    WHERE NOT pub_date > '2005-1-3'
+    AND NOT headline = 'Hello'
+
+Note the second example is more restrictive.
+
+annotate
+~~~~~~~~
+
+.. method:: annotate(*args, **kwargs)
+
+.. versionadded:: 1.1
+
+Annotates each object in the ``QuerySet`` with the provided list of
+aggregate values (averages, sums, etc) that have been computed over
+the objects that are related to the objects in the ``QuerySet``.
+Each argument to ``annotate()`` is an annotation that will be added
+to each object in the ``QuerySet`` that is returned.
+
+The aggregation functions that are provided by Django are described
+in `Aggregation Functions`_ below.
+
+Annotations specified using keyword arguments will use the keyword as
+the alias for the annotation. Anonymous arguments will have an alias
+generated for them based upon the name of the aggregate function and
+the model field that is being aggregated.
+
+For example, if you were manipulating a list of blogs, you may want
+to determine how many entries have been made in each blog::
+
+    >>> q = Blog.objects.annotate(Count('entry'))
+    # The name of the first blog
+    >>> q[0].name
+    'Blogasaurus'
+    # The number of entries on the first blog
+    >>> q[0].entry__count
+    42
+
+The ``Blog`` model doesn't define an ``entry__count`` attribute by itself,
+but by using a keyword argument to specify the aggregate function, you can
+control the name of the annotation::
+
+    >>> q = Blog.objects.annotate(number_of_entries=Count('entry'))
+    # The number of entries on the first blog, using the name provided
+    >>> q[0].number_of_entries
+    42
+
+For an in-depth discussion of aggregation, see :doc:`the topic guide on
+Aggregation </topics/db/aggregation>`.
+
+order_by
+~~~~~~~~
+
+.. method:: order_by(*fields)
+
+By default, results returned by a ``QuerySet`` are ordered by the ordering
+tuple given by the ``ordering`` option in the model's ``Meta``. You can
+override this on a per-``QuerySet`` basis by using the ``order_by`` method.
+
+Example::
+
+    Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')
+
+The result above will be ordered by ``pub_date`` descending, then by
+``headline`` ascending. The negative sign in front of ``"-pub_date"`` indicates
+*descending* order. Ascending order is implied. To order randomly, use ``"?"``,
+like so::
+
+    Entry.objects.order_by('?')
+
+Note: ``order_by('?')`` queries may be expensive and slow, depending on the
+database backend you're using.
+
+To order by a field in a different model, use the same syntax as when you are
+querying across model relations. That is, the name of the field, followed by a
+double underscore (``__``), followed by the name of the field in the new model,
+and so on for as many models as you want to join. For example::
+
+    Entry.objects.order_by('blog__name', 'headline')
+
+If you try to order by a field that is a relation to another model, Django will
+use the default ordering on the related model (or order by the related model's
+primary key if there is no ``Meta.ordering`` specified. For example::
+
+    Entry.objects.order_by('blog')
+
+...is identical to::
+
+    Entry.objects.order_by('blog__id')
+
+...since the ``Blog`` model has no default ordering specified.
+
+Be cautious when ordering by fields in related models if you are also using
+``distinct()``. See the note in :meth:`distinct` for an explanation of how
+related model ordering can change the expected results.
+
+It is permissible to specify a multi-valued field to order the results by (for
+example, a ``ManyToMany`` field). Normally this won't be a sensible thing to
+do and it's really an advanced usage feature. However, if you know that your
+queryset's filtering or available data implies that there will only be one
+ordering piece of data for each of the main items you are selecting, the
+ordering may well be exactly what you want to do. Use ordering on multi-valued
+fields with care and make sure the results are what you expect.
+
+.. versionadded:: 1.0
+
+The syntax for ordering across related models has changed. See the `Django 0.96
+documentation`_ for the old behaviour.
+
+.. _Django 0.96 documentation: http://www.djangoproject.com/documentation/0.96/model-api/#floatfield
+
+There's no way to specify whether ordering should be case sensitive. With
+respect to case-sensitivity, Django will order results however your database
+backend normally orders them.
+
+If you don't want any ordering to be applied to a query, not even the default
+ordering, call ``order_by()`` with no parameters.
+
+.. versionadded:: 1.1
+
+You can tell if a query is ordered or not by checking the
+:attr:`QuerySet.ordered` attribute, which will be ``True`` if the
+``QuerySet`` has been ordered in any way.
+
+reverse
+~~~~~~~
+
+.. method:: reverse()
+
+.. versionadded:: 1.0
+
+Use the ``reverse()`` method to reverse the order in which a queryset's
+elements are returned. Calling ``reverse()`` a second time restores the
+ordering back to the normal direction.
+
+To retrieve the ''last'' five items in a queryset, you could do this::
+
+    my_queryset.reverse()[:5]
+
+Note that this is not quite the same as slicing from the end of a sequence in
+Python. The above example will return the last item first, then the
+penultimate item and so on. If we had a Python sequence and looked at
+``seq[-5:]``, we would see the fifth-last item first. Django doesn't support
+that mode of access (slicing from the end), because it's not possible to do it
+efficiently in SQL.
+
+Also, note that ``reverse()`` should generally only be called on a
+``QuerySet`` which has a defined ordering (e.g., when querying against
+a model which defines a default ordering, or when using
+``order_by()``). If no such ordering is defined for a given
+``QuerySet``, calling ``reverse()`` on it has no real effect (the
+ordering was undefined prior to calling ``reverse()``, and will remain
+undefined afterward).
+
+distinct
+~~~~~~~~
+
+.. method:: distinct()
+
+Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This
+eliminates duplicate rows from the query results.
+
+By default, a ``QuerySet`` will not eliminate duplicate rows. In practice, this
+is rarely a problem, because simple queries such as ``Blog.objects.all()``
+don't introduce the possibility of duplicate result rows. However, if your
+query spans multiple tables, it's possible to get duplicate results when a
+``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
+
+.. note::
+    Any fields used in an :meth:`order_by` call are included in the SQL
+    ``SELECT`` columns. This can sometimes lead to unexpected results when
+    used in conjunction with ``distinct()``. If you order by fields from a
+    related model, those fields will be added to the selected columns and they
+    may make otherwise duplicate rows appear to be distinct. Since the extra
+    columns don't appear in the returned results (they are only there to
+    support ordering), it sometimes looks like non-distinct results are being
+    returned.
+
+    Similarly, if you use a ``values()`` query to restrict the columns
+    selected, the columns used in any ``order_by()`` (or default model
+    ordering) will still be involved and may affect uniqueness of the results.
+
+    The moral here is that if you are using ``distinct()`` be careful about
+    ordering by related models. Similarly, when using ``distinct()`` and
+    ``values()`` together, be careful when ordering by fields not in the
+    ``values()`` call.
+
+values
+~~~~~~
+
+.. method:: values(*fields)
+
+Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that returns dictionaries when
+used as an iterable, rather than model-instance objects.
+
+Each of those dictionaries represents an object, with the keys corresponding to
+the attribute names of model objects.
+
+This example compares the dictionaries of ``values()`` with the normal model
+objects::
+
+    # This list contains a Blog object.
+    >>> Blog.objects.filter(name__startswith='Beatles')
+    [<Blog: Beatles Blog>]
+
+    # This list contains a dictionary.
+    >>> Blog.objects.filter(name__startswith='Beatles').values()
+    [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]
+
+``values()`` takes optional positional arguments, ``*fields``, which specify
+field names to which the ``SELECT`` should be limited. If you specify the
+fields, each dictionary will contain only the field keys/values for the fields
+you specify. If you don't specify the fields, each dictionary will contain a
+key and value for every field in the database table.
+
+Example::
+
+    >>> Blog.objects.values()
+    [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
+    >>> Blog.objects.values('id', 'name')
+    [{'id': 1, 'name': 'Beatles Blog'}]
+
+A couple of subtleties that are worth mentioning:
+
+    * The ``values()`` method does not return anything for
+      :class:`~django.db.models.ManyToManyField` attributes and will raise an
+      error if you try to pass in this type of field to it.
+    * If you have a field called ``foo`` that is a
+      :class:`~django.db.models.ForeignKey`, the default ``values()`` call
+      will return a dictionary key called ``foo_id``, since this is the name
+      of the hidden model attribute that stores the actual value (the ``foo``
+      attribute refers to the related model). When you are calling
+      ``values()`` and passing in field names, you can pass in either ``foo``
+      or ``foo_id`` and you will get back the same thing (the dictionary key
+      will match the field name you passed in).
+
+      For example::
+
+        >>> Entry.objects.values()
+        [{'blog_id': 1, 'headline': u'First Entry', ...}, ...]
+
+        >>> Entry.objects.values('blog')
+        [{'blog': 1}, ...]
+
+        >>> Entry.objects.values('blog_id')
+        [{'blog_id': 1}, ...]
+
+    * When using ``values()`` together with ``distinct()``, be aware that
+      ordering can affect the results. See the note in :meth:`distinct` for
+      details.
+
+    * If you use a ``values()`` clause after an ``extra()`` clause,
+      any fields defined by a ``select`` argument in the ``extra()``
+      must be explicitly included in the ``values()`` clause. However,
+      if the ``extra()`` clause is used after the ``values()``, the
+      fields added by the select will be included automatically.
+
+.. versionadded:: 1.0
+
+Previously, it was not possible to pass ``blog_id`` to ``values()`` in the above
+example, only ``blog``.
+
+A ``ValuesQuerySet`` is useful when you know you're only going to need values
+from a small number of the available fields and you won't need the
+functionality of a model instance object. It's more efficient to select only
+the fields you need to use.
+
+Finally, note a ``ValuesQuerySet`` is a subclass of ``QuerySet``, so it has all
+methods of ``QuerySet``. You can call ``filter()`` on it, or ``order_by()``, or
+whatever. Yes, that means these two calls are identical::
+
+    Blog.objects.values().order_by('id')
+    Blog.objects.order_by('id').values()
+
+The people who made Django prefer to put all the SQL-affecting methods first,
+followed (optionally) by any output-affecting methods (such as ``values()``),
+but it doesn't really matter. This is your chance to really flaunt your
+individualism.
+
+values_list
+~~~~~~~~~~~
+
+.. method:: values_list(*fields)
+
+.. versionadded:: 1.0
+
+This is similar to ``values()`` except that instead of returning dictionaries,
+it returns tuples when iterated over. Each tuple contains the value from the
+respective field passed into the ``values_list()`` call -- so the first item is
+the first field, etc. For example::
+
+    >>> Entry.objects.values_list('id', 'headline')
+    [(1, u'First entry'), ...]
+
+If you only pass in a single field, you can also pass in the ``flat``
+parameter. If ``True``, this will mean the returned results are single values,
+rather than one-tuples. An example should make the difference clearer::
+
+    >>> Entry.objects.values_list('id').order_by('id')
+    [(1,), (2,), (3,), ...]
+
+    >>> Entry.objects.values_list('id', flat=True).order_by('id')
+    [1, 2, 3, ...]
+
+It is an error to pass in ``flat`` when there is more than one field.
+
+If you don't pass any values to ``values_list()``, it will return all the
+fields in the model, in the order they were declared.
+
+dates
+~~~~~
+
+.. method:: dates(field, kind, order='ASC')
+
+Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of
+``datetime.datetime`` objects representing all available dates of a particular
+kind within the contents of the ``QuerySet``.
+
+``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your
+model.
+
+``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each
+``datetime.datetime`` object in the result list is "truncated" to the given
+``type``.
+
+    * ``"year"`` returns a list of all distinct year values for the field.
+    * ``"month"`` returns a list of all distinct year/month values for the field.
+    * ``"day"`` returns a list of all distinct year/month/day values for the field.
+
+``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
+``'DESC'``. This specifies how to order the results.
+
+Examples::
+
+    >>> Entry.objects.dates('pub_date', 'year')
+    [datetime.datetime(2005, 1, 1)]
+    >>> Entry.objects.dates('pub_date', 'month')
+    [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
+    >>> Entry.objects.dates('pub_date', 'day')
+    [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
+    >>> Entry.objects.dates('pub_date', 'day', order='DESC')
+    [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
+    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
+    [datetime.datetime(2005, 3, 20)]
+
+none
+~~~~
+
+.. method:: none()
+
+.. versionadded:: 1.0
+
+Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to
+an empty list. This can be used in cases where you know that you should
+return an empty result set and your caller is expecting a ``QuerySet``
+object (instead of returning an empty list, for example.)
+
+Examples::
+
+    >>> Entry.objects.none()
+    []
+
+all
+~~~
+
+.. method:: all()
+
+.. versionadded:: 1.0
+
+Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you
+pass in). This can be useful in some situations where you might want to pass
+in either a model manager or a ``QuerySet`` and do further filtering on the
+result. You can safely call ``all()`` on either object and then you'll
+definitely have a ``QuerySet`` to work with.
+
+.. _select-related:
+
+select_related
+~~~~~~~~~~~~~~
+
+.. method:: select_related()
+
+Returns a ``QuerySet`` that will automatically "follow" foreign-key
+relationships, selecting that additional related-object data when it executes
+its query. This is a performance booster which results in (sometimes much)
+larger queries but means later use of foreign-key relationships won't require
+database queries.
+
+The following examples illustrate the difference between plain lookups and
+``select_related()`` lookups. Here's standard lookup::
+
+    # Hits the database.
+    e = Entry.objects.get(id=5)
+
+    # Hits the database again to get the related Blog object.
+    b = e.blog
+
+And here's ``select_related`` lookup::
+
+    # Hits the database.
+    e = Entry.objects.select_related().get(id=5)
+
+    # Doesn't hit the database, because e.blog has been prepopulated
+    # in the previous query.
+    b = e.blog
+
+``select_related()`` follows foreign keys as far as possible. If you have the
+following models::
+
+    class City(models.Model):
+        # ...
+
+    class Person(models.Model):
+        # ...
+        hometown = models.ForeignKey(City)
+
+    class Book(models.Model):
+        # ...
+        author = models.ForeignKey(Person)
+
+...then a call to ``Book.objects.select_related().get(id=4)`` will cache the
+related ``Person`` *and* the related ``City``::
+
+    b = Book.objects.select_related().get(id=4)
+    p = b.author         # Doesn't hit the database.
+    c = p.hometown       # Doesn't hit the database.
+
+    b = Book.objects.get(id=4) # No select_related() in this example.
+    p = b.author         # Hits the database.
+    c = p.hometown       # Hits the database.
+
+Note that, by default, ``select_related()`` does not follow foreign keys that
+have ``null=True``.
+
+Usually, using ``select_related()`` can vastly improve performance because your
+app can avoid many database calls. However, in situations with deeply nested
+sets of relationships ``select_related()`` can sometimes end up following "too
+many" relations, and can generate queries so large that they end up being slow.
+
+In these situations, you can use the ``depth`` argument to ``select_related()``
+to control how many "levels" of relations ``select_related()`` will actually
+follow::
+
+    b = Book.objects.select_related(depth=1).get(id=4)
+    p = b.author         # Doesn't hit the database.
+    c = p.hometown       # Requires a database call.
+
+Sometimes you only want to access specific models that are related to your root
+model, not all of the related models. In these cases, you can pass the related
+field names to ``select_related()`` and it will only follow those relations.
+You can even do this for models that are more than one relation away by
+separating the field names with double underscores, just as for filters. For
+example, if you have this model::
+
+    class Room(models.Model):
+        # ...
+        building = models.ForeignKey(...)
+
+    class Group(models.Model):
+        # ...
+        teacher = models.ForeignKey(...)
+        room = models.ForeignKey(Room)
+        subject = models.ForeignKey(...)
+
+...and you only needed to work with the ``room`` and ``subject`` attributes,
+you could write this::
+
+    g = Group.objects.select_related('room', 'subject')
+
+This is also valid::
+
+    g = Group.objects.select_related('room__building', 'subject')
+
+...and would also pull in the ``building`` relation.
+
+You can refer to any ``ForeignKey`` or ``OneToOneField`` relation in
+the list of fields passed to ``select_related``. Ths includes foreign
+keys that have ``null=True`` (unlike the default ``select_related()``
+call). It's an error to use both a list of fields and the ``depth``
+parameter in the same ``select_related()`` call, since they are
+conflicting options.
+
+.. versionadded:: 1.0
+
+Both the ``depth`` argument and the ability to specify field names in the call
+to ``select_related()`` are new in Django version 1.0.
+
+.. versionchanged:: 1.2
+
+You can also refer to the reverse direction of a ``OneToOneFields`` in
+the list of fields passed to ``select_related`` -- that is, you can traverse
+a ``OneToOneField`` back to the object on which the field is defined. Instead
+of specifying the field name, use the ``related_name`` for the field on the
+related object.
+
+``OneToOneFields`` will not be traversed in the reverse direction if you
+are performing a depth-based ``select_related``.
+
+extra
+~~~~~
+
+.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
+
+Sometimes, the Django query syntax by itself can't easily express a complex
+``WHERE`` clause. For these edge cases, Django provides the ``extra()``
+``QuerySet`` modifier -- a hook for injecting specific clauses into the SQL
+generated by a ``QuerySet``.
+
+By definition, these extra lookups may not be portable to different database
+engines (because you're explicitly writing SQL code) and violate the DRY
+principle, so you should avoid them if possible.
+
+Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None
+of the arguments is required, but you should use at least one of them.
+
+    * ``select``
+        The ``select`` argument lets you put extra fields in the ``SELECT`` clause.
+        It should be a dictionary mapping attribute names to SQL clauses to use to
+        calculate that attribute.
+
+        Example::
+
+            Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
+
+        As a result, each ``Entry`` object will have an extra attribute,
+        ``is_recent``, a boolean representing whether the entry's ``pub_date`` is
+        greater than Jan. 1, 2006.
+
+        Django inserts the given SQL snippet directly into the ``SELECT``
+        statement, so the resulting SQL of the above example would be something
+        like::
+
+            SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
+            FROM blog_entry;
+
+
+        The next example is more advanced; it does a subquery to give each
+        resulting ``Blog`` object an ``entry_count`` attribute, an integer count
+        of associated ``Entry`` objects::
+
+            Blog.objects.extra(
+                select={
+                    'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
+                },
+            )
+
+        (In this particular case, we're exploiting the fact that the query will
+        already contain the ``blog_blog`` table in its ``FROM`` clause.)
+
+        The resulting SQL of the above example would be::
+
+            SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
+            FROM blog_blog;
+
+        Note that the parenthesis required by most database engines around
+        subqueries are not required in Django's ``select`` clauses. Also note that
+        some database backends, such as some MySQL versions, don't support
+        subqueries.
+
+        .. versionadded:: 1.0
+
+        In some rare cases, you might wish to pass parameters to the SQL fragments
+        in ``extra(select=...)``. For this purpose, use the ``select_params``
+        parameter. Since ``select_params`` is a sequence and the ``select``
+        attribute is a dictionary, some care is required so that the parameters
+        are matched up correctly with the extra select pieces.  In this situation,
+        you should use a ``django.utils.datastructures.SortedDict`` for the
+        ``select`` value, not just a normal Python dictionary.
+
+        This will work, for example::
+
+            Blog.objects.extra(
+                select=SortedDict([('a', '%s'), ('b', '%s')]),
+                select_params=('one', 'two'))
+
+        The only thing to be careful about when using select parameters in
+        ``extra()`` is to avoid using the substring ``"%%s"`` (that's *two*
+        percent characters before the ``s``) in the select strings. Django's
+        tracking of parameters looks for ``%s`` and an escaped ``%`` character
+        like this isn't detected. That will lead to incorrect results.
+
+    * ``where`` / ``tables``
+        You can define explicit SQL ``WHERE`` clauses -- perhaps to perform
+        non-explicit joins -- by using ``where``. You can manually add tables to
+        the SQL ``FROM`` clause by using ``tables``.
+
+        ``where`` and ``tables`` both take a list of strings. All ``where``
+        parameters are "AND"ed to any other search criteria.
+
+        Example::
+
+            Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])
+
+        ...translates (roughly) into the following SQL::
+
+            SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20);
+
+        Be careful when using the ``tables`` parameter if you're specifying
+        tables that are already used in the query. When you add extra tables
+        via the ``tables`` parameter, Django assumes you want that table included
+        an extra time, if it is already included. That creates a problem,
+        since the table name will then be given an alias. If a table appears
+        multiple times in an SQL statement, the second and subsequent occurrences
+        must use aliases so the database can tell them apart. If you're
+        referring to the extra table you added in the extra ``where`` parameter
+        this is going to cause errors.
+
+        Normally you'll only be adding extra tables that don't already appear in
+        the query. However, if the case outlined above does occur, there are a few
+        solutions. First, see if you can get by without including the extra table
+        and use the one already in the query. If that isn't possible, put your
+        ``extra()`` call at the front of the queryset construction so that your
+        table is the first use of that table. Finally, if all else fails, look at
+        the query produced and rewrite your ``where`` addition to use the alias
+        given to your extra table. The alias will be the same each time you
+        construct the queryset in the same way, so you can rely upon the alias
+        name to not change.
+
+    * ``order_by``
+        If you need to order the resulting queryset using some of the new fields
+        or tables you have included via ``extra()`` use the ``order_by`` parameter
+        to ``extra()`` and pass in a sequence of strings. These strings should
+        either be model fields (as in the normal ``order_by()`` method on
+        querysets), of the form ``table_name.column_name`` or an alias for a column
+        that you specified in the ``select`` parameter to ``extra()``.
+
+        For example::
+
+            q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})
+            q = q.extra(order_by = ['-is_recent'])
+
+        This would sort all the items for which ``is_recent`` is true to the front
+        of the result set (``True`` sorts before ``False`` in a descending
+        ordering).
+
+        This shows, by the way, that you can make multiple calls to
+        ``extra()`` and it will behave as you expect (adding new constraints each
+        time).
+
+    * ``params``
+        The ``where`` parameter described above may use standard Python database
+        string placeholders -- ``'%s'`` to indicate parameters the database engine
+        should automatically quote. The ``params`` argument is a list of any extra
+        parameters to be substituted.
+
+        Example::
+
+            Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
+
+        Always use ``params`` instead of embedding values directly into ``where``
+        because ``params`` will ensure values are quoted correctly according to
+        your particular backend. (For example, quotes will be escaped correctly.)
+
+        Bad::
+
+            Entry.objects.extra(where=["headline='Lennon'"])
+
+        Good::
+
+            Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
+
+defer
+~~~~~
+
+.. method:: defer(*fields)
+
+.. versionadded:: 1.1
+
+In some complex data-modeling situations, your models might contain a lot of
+fields, some of which could contain a lot of data (for example, text fields),
+or require expensive processing to convert them to Python objects. If you are
+using the results of a queryset in some situation where you know you don't
+need those particular fields, you can tell Django not to retrieve them from
+the database.
+
+This is done by passing the names of the fields to not load to ``defer()``::
+
+    Entry.objects.defer("headline", "body")
+
+A queryset that has deferred fields will still return model instances. Each
+deferred field will be retrieved from the database if you access that field
+(one at a time, not all the deferred fields at once).
+
+You can make multiple calls to ``defer()``. Each call adds new fields to the
+deferred set::
+
+    # Defers both the body and headline fields.
+    Entry.objects.defer("body").filter(rating=5).defer("headline")
+
+The order in which fields are added to the deferred set does not matter.
+Calling ``defer()`` with a field name that has already been deferred is
+harmless (the field will still be deferred).
+
+You can defer loading of fields in related models (if the related models are
+loading via ``select_related()``) by using the standard double-underscore
+notation to separate related fields::
+
+    Blog.objects.select_related().defer("entry__headline", "entry__body")
+
+If you want to clear the set of deferred fields, pass ``None`` as a parameter
+to ``defer()``::
+
+    # Load all fields immediately.
+    my_queryset.defer(None)
+
+Some fields in a model won't be deferred, even if you ask for them. You can
+never defer the loading of the primary key. If you are using
+``select_related()`` to retrieve other models at the same time you shouldn't
+defer the loading of the field that connects from the primary model to the
+related one (at the moment, that doesn't raise an error, but it will
+eventually).
+
+.. note::
+
+    The ``defer()`` method (and its cousin, ``only()``, below) are only for
+    advanced use-cases. They provide an optimization for when you have
+    analyzed your queries closely and understand *exactly* what information
+    you need and have measured that the difference between returning the
+    fields you need and the full set of fields for the model will be
+    significant. When you are initially developing your applications, don't
+    bother using ``defer()``; leave it until your query construction has
+    settled down and you understand where the hot-points are.
+
+only
+~~~~
+
+.. method:: only(*fields)
+
+.. versionadded:: 1.1
+
+The ``only()`` method is more or less the opposite of ``defer()``. You
+call it with the fields that should *not* be deferred when retrieving a model.
+If you have a model where almost all the fields need to be deferred, using
+``only()`` to specify the complementary set of fields could result in simpler
+code.
+
+If you have a model with fields ``name``, ``age`` and ``biography``, the
+following two querysets are the same, in terms of deferred fields::
+
+    Person.objects.defer("age", "biography")
+    Person.objects.only("name")
+
+Whenever you call ``only()`` it *replaces* the set of fields to load
+immediately. The method's name is mnemonic: **only** those fields are loaded
+immediately; the remainder are deferred. Thus, successive calls to ``only()``
+result in only the final fields being considered::
+
+    # This will defer all fields except the headline.
+    Entry.objects.only("body", "rating").only("headline")
+
+Since ``defer()`` acts incrementally (adding fields to the deferred list), you
+can combine calls to ``only()`` and ``defer()`` and things will behave
+logically::
+
+    # Final result is that everything except "headline" is deferred.
+    Entry.objects.only("headline", "body").defer("body")
+
+    # Final result loads headline and body immediately (only() replaces any
+    # existing set of fields).
+    Entry.objects.defer("body").only("headline", "body")
+
+using
+~~~~~
+
+.. method:: using(alias)
+
+.. versionadded:: 1.2
+
+This method is for controlling which database the ``QuerySet`` will be
+evaluated against if you are using more than one database.  The only argument
+this method takes is the alias of a database, as defined in
+:setting:`DATABASES`.
+
+For example::
+
+    # queries the database with the 'default' alias.
+    >>> Entry.objects.all()
+
+    # queries the database with the 'backup' alias
+    >>> Entry.objects.using('backup')
+
+
+Methods that do not return QuerySets
+------------------------------------
+
+The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
+something *other than* a ``QuerySet``.
+
+These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
+they query the database each time they're called.
+
+get
+~~~
+
+.. method:: get(**kwargs)
+
+Returns the object matching the given lookup parameters, which should be in
+the format described in `Field lookups`_.
+
+``get()`` raises ``MultipleObjectsReturned`` if more than one object was
+found. The ``MultipleObjectsReturned`` exception is an attribute of the model
+class.
+
+``get()`` raises a ``DoesNotExist`` exception if an object wasn't found for
+the given parameters. This exception is also an attribute of the model class.
+Example::
+
+    Entry.objects.get(id='foo') # raises Entry.DoesNotExist
+
+The ``DoesNotExist`` exception inherits from
+``django.core.exceptions.ObjectDoesNotExist``, so you can target multiple
+``DoesNotExist`` exceptions. Example::
+
+    from django.core.exceptions import ObjectDoesNotExist
+    try:
+        e = Entry.objects.get(id=3)
+        b = Blog.objects.get(id=1)
+    except ObjectDoesNotExist:
+        print "Either the entry or blog doesn't exist."
+
+create
+~~~~~~
+
+.. method:: create(**kwargs)
+
+A convenience method for creating an object and saving it all in one step.  Thus::
+
+    p = Person.objects.create(first_name="Bruce", last_name="Springsteen")
+
+and::
+
+    p = Person(first_name="Bruce", last_name="Springsteen")
+    p.save(force_insert=True)
+
+are equivalent.
+
+The :ref:`force_insert <ref-models-force-insert>` parameter is documented
+elsewhere, but all it means is that a new object will always be created.
+Normally you won't need to worry about this. However, if your model contains a
+manual primary key value that you set and if that value already exists in the
+database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
+primary keys must be unique. So remember to be prepared to handle the exception
+if you are using manual primary keys.
+
+get_or_create
+~~~~~~~~~~~~~
+
+.. method:: get_or_create(**kwargs)
+
+A convenience method for looking up an object with the given kwargs, creating
+one if necessary.
+
+Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or
+created object and ``created`` is a boolean specifying whether a new object was
+created.
+
+This is meant as a shortcut to boilerplatish code and is mostly useful for
+data-import scripts. For example::
+
+    try:
+        obj = Person.objects.get(first_name='John', last_name='Lennon')
+    except Person.DoesNotExist:
+        obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))
+        obj.save()
+
+This pattern gets quite unwieldy as the number of fields in a model goes up.
+The above example can be rewritten using ``get_or_create()`` like so::
+
+    obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon',
+                      defaults={'birthday': date(1940, 10, 9)})
+
+Any keyword arguments passed to ``get_or_create()`` -- *except* an optional one
+called ``defaults`` -- will be used in a ``get()`` call. If an object is found,
+``get_or_create()`` returns a tuple of that object and ``False``. If an object
+is *not* found, ``get_or_create()`` will instantiate and save a new object,
+returning a tuple of the new object and ``True``. The new object will be
+created roughly according to this algorithm::
+
+    defaults = kwargs.pop('defaults', {})
+    params = dict([(k, v) for k, v in kwargs.items() if '__' not in k])
+    params.update(defaults)
+    obj = self.model(**params)
+    obj.save()
+
+In English, that means start with any non-``'defaults'`` keyword argument that
+doesn't contain a double underscore (which would indicate a non-exact lookup).
+Then add the contents of ``defaults``, overriding any keys if necessary, and
+use the result as the keyword arguments to the model class. As hinted at
+above, this is a simplification of the algorithm that is used, but it contains
+all the pertinent details. The internal implementation has some more
+error-checking than this and handles some extra edge-conditions; if you're
+interested, read the code.
+
+If you have a field named ``defaults`` and want to use it as an exact lookup in
+``get_or_create()``, just use ``'defaults__exact'``, like so::
+
+    Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
+
+
+The ``get_or_create()`` method has similar error behaviour to ``create()``
+when you are using manually specified primary keys. If an object needs to be
+created and the key already exists in the database, an ``IntegrityError`` will
+be raised.
+
+Finally, a word on using ``get_or_create()`` in Django views. As mentioned
+earlier, ``get_or_create()`` is mostly useful in scripts that need to parse
+data and create new records if existing ones aren't available. But if you need
+to use ``get_or_create()`` in a view, please make sure to use it only in
+``POST`` requests unless you have a good reason not to. ``GET`` requests
+shouldn't have any effect on data; use ``POST`` whenever a request to a page
+has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
+
+.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
+
+count
+~~~~~
+
+.. method:: count()
+
+Returns an integer representing the number of objects in the database matching
+the ``QuerySet``. ``count()`` never raises exceptions.
+
+Example::
+
+    # Returns the total number of entries in the database.
+    Entry.objects.count()
+
+    # Returns the number of entries whose headline contains 'Lennon'
+    Entry.objects.filter(headline__contains='Lennon').count()
+
+``count()`` performs a ``SELECT COUNT(*)`` behind the scenes, so you should
+always use ``count()`` rather than loading all of the record into Python
+objects and calling ``len()`` on the result (unless you need to load the
+objects into memory anyway, in which case ``len()`` will be faster).
+
+Depending on which database you're using (e.g. PostgreSQL vs. MySQL),
+``count()`` may return a long integer instead of a normal Python integer. This
+is an underlying implementation quirk that shouldn't pose any real-world
+problems.
+
+in_bulk
+~~~~~~~
+
+.. method:: in_bulk(id_list)
+
+Takes a list of primary-key values and returns a dictionary mapping each
+primary-key value to an instance of the object with the given ID.
+
+Example::
+
+    >>> Blog.objects.in_bulk([1])
+    {1: <Blog: Beatles Blog>}
+    >>> Blog.objects.in_bulk([1, 2])
+    {1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
+    >>> Blog.objects.in_bulk([])
+    {}
+
+If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
+
+iterator
+~~~~~~~~
+
+.. method:: iterator()
+
+Evaluates the ``QuerySet`` (by performing the query) and returns an
+`iterator`_ over the results. A ``QuerySet`` typically caches its
+results internally so that repeated evaluations do not result in
+additional queries; ``iterator()`` will instead read results directly,
+without doing any caching at the ``QuerySet`` level. For a
+``QuerySet`` which returns a large number of objects, this often
+results in better performance and a significant reduction in memory
+
+Note that using ``iterator()`` on a ``QuerySet`` which has already
+been evaluated will force it to evaluate again, repeating the query.
+
+.. _iterator: http://www.python.org/dev/peps/pep-0234/
+
+latest
+~~~~~~
+
+.. method:: latest(field_name=None)
+
+Returns the latest object in the table, by date, using the ``field_name``
+provided as the date field.
+
+This example returns the latest ``Entry`` in the table, according to the
+``pub_date`` field::
+
+    Entry.objects.latest('pub_date')
+
+If your model's ``Meta`` specifies ``get_latest_by``, you can leave off the
+``field_name`` argument to ``latest()``. Django will use the field specified in
+``get_latest_by`` by default.
+
+Like ``get()``, ``latest()`` raises ``DoesNotExist`` if an object doesn't
+exist with the given parameters.
+
+Note ``latest()`` exists purely for convenience and readability.
+
+aggregate
+~~~~~~~~~
+
+.. method:: aggregate(*args, **kwargs)
+
+.. versionadded:: 1.1
+
+Returns a dictionary of aggregate values (averages, sums, etc) calculated
+over the ``QuerySet``. Each argument to ``aggregate()`` specifies
+a value that will be included in the dictionary that is returned.
+
+The aggregation functions that are provided by Django are described
+in `Aggregation Functions`_ below.
+
+Aggregates specified using keyword arguments will use the keyword as
+the name for the annotation. Anonymous arguments will have an name
+generated for them based upon the name of the aggregate function and
+the model field that is being aggregated.
+
+For example, if you were manipulating blog entries, you may want to know
+the number of authors that have contributed blog entries::
+
+    >>> q = Blog.objects.aggregate(Count('entry'))
+    {'entry__count': 16}
+
+By using a keyword argument to specify the aggregate function, you can
+control the name of the aggregation value that is returned::
+
+    >>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))
+    {'number_of_entries': 16}
+
+For an in-depth discussion of aggregation, see :doc:`the topic guide on
+Aggregation </topics/db/aggregation>`.
+
+exists
+~~~~~~
+
+.. method:: exists()
+
+.. versionadded:: 1.2
+
+Returns ``True`` if the :class:`QuerySet` contains any results, and ``False``
+if not. This tries to perform the query in the simplest and fastest way
+possible, but it *does* execute nearly the same query. This means that calling
+:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by
+a large degree.  If ``some_query_set`` has not yet been evaluated, but you know
+that it will be at some point, then using ``some_query_set.exists()`` will do
+more overall work (an additional query) than simply using
+``bool(some_query_set)``.
+
+update
+~~~~~~
+
+.. method:: update(**kwargs)
+
+Performs an SQL update query for the specified fields, and returns
+the number of rows affected. The ``update()`` method is applied instantly and
+the only restriction on the :class:`QuerySet` that is updated is that it can
+only update columns in the model's main table. Filtering based on related
+fields is still possible. You cannot call ``update()`` on a
+:class:`QuerySet` that has had a slice taken or can otherwise no longer be
+filtered.
+
+For example, if you wanted to update all the entries in a particular blog
+to use the same headline::
+
+    >>> b = Blog.objects.get(pk=1)
+
+    # Update all the headlines belonging to this Blog.
+    >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same')
+
+The ``update()`` method does a bulk update and does not call any ``save()``
+methods on your models, nor does it emit the ``pre_save`` or ``post_save``
+signals (which are a consequence of calling ``save()``).
+
+delete
+~~~~~~
+
+.. method:: delete()
+
+Performs an SQL delete query on all rows in the :class:`QuerySet`. The
+``delete()`` is applied instantly. You cannot call ``delete()`` on a
+:class:`QuerySet` that has had a slice taken or can otherwise no longer be
+filtered.
+
+For example, to delete all the entries in a particular blog::
+
+    >>> b = Blog.objects.get(pk=1)
+
+    # Delete all the entries belonging to this Blog.
+    >>> Entry.objects.filter(blog=b).delete()
+
+Django emulates the SQL constraint ``ON DELETE CASCADE`` -- in other words, any
+objects with foreign keys pointing at the objects to be deleted will be deleted
+along with them.  For example::
+
+    blogs = Blog.objects.all()
+    # This will delete all Blogs and all of their Entry objects.
+    blogs.delete()
+
+The ``delete()`` method does a bulk delete and does not call any ``delete()``
+methods on your models. It does, however, emit the
+:data:`~django.db.models.signals.pre_delete` and
+:data:`~django.db.models.signals.post_delete` signals for all deleted objects
+(including cascaded deletions).
+
+.. _field-lookups:
+
+Field lookups
+-------------
+
+Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're
+specified as keyword arguments to the ``QuerySet`` methods ``filter()``,
+``exclude()`` and ``get()``.
+
+For an introduction, see :ref:`field-lookups-intro`.
+
+.. fieldlookup:: exact
+
+exact
+~~~~~
+
+Exact match. If the value provided for comparison is ``None``, it will
+be interpreted as an SQL ``NULL`` (See isnull_ for more details).
+
+Examples::
+
+    Entry.objects.get(id__exact=14)
+    Entry.objects.get(id__exact=None)
+
+SQL equivalents::
+
+    SELECT ... WHERE id = 14;
+    SELECT ... WHERE id IS NULL;
+
+.. versionchanged:: 1.0
+   The semantics of ``id__exact=None`` have changed in Django 1.0. Previously,
+   it was (intentionally) converted to ``WHERE id = NULL`` at the SQL level,
+   which would never match anything. It has now been changed to behave the
+   same as ``id__isnull=True``.
+
+.. admonition:: MySQL comparisons
+
+    In MySQL, a database table's "collation" setting determines whether
+    ``exact`` comparisons are case-sensitive. This is a database setting, *not*
+    a Django setting. It's possible to configure your MySQL tables to use
+    case-sensitive comparisons, but some trade-offs are involved. For more
+    information about this, see the :ref:`collation section <mysql-collation>`
+    in the :doc:`databases </ref/databases>` documentation.
+
+.. fieldlookup:: iexact
+
+iexact
+~~~~~~
+
+Case-insensitive exact match.
+
+Example::
+
+    Blog.objects.get(name__iexact='beatles blog')
+
+SQL equivalent::
+
+    SELECT ... WHERE name ILIKE 'beatles blog';
+
+Note this will match ``'Beatles Blog'``, ``'beatles blog'``, ``'BeAtLes
+BLoG'``, etc.
+
+.. admonition:: SQLite users
+
+    When using the SQLite backend and Unicode (non-ASCII) strings, bear in
+    mind the :ref:`database note <sqlite-string-matching>` about string
+    comparisons. SQLite does not do case-insensitive matching for Unicode
+    strings.
+
+.. fieldlookup:: contains
+
+contains
+~~~~~~~~
+
+Case-sensitive containment test.
+
+Example::
+
+    Entry.objects.get(headline__contains='Lennon')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline LIKE '%Lennon%';
+
+Note this will match the headline ``'Today Lennon honored'`` but not
+``'today lennon honored'``.
+
+SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains`` acts
+like ``icontains`` for SQLite.
+
+.. fieldlookup:: icontains
+
+icontains
+~~~~~~~~~
+
+Case-insensitive containment test.
+
+Example::
+
+    Entry.objects.get(headline__icontains='Lennon')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline ILIKE '%Lennon%';
+
+.. admonition:: SQLite users
+
+    When using the SQLite backend and Unicode (non-ASCII) strings, bear in
+    mind the :ref:`database note <sqlite-string-matching>` about string
+    comparisons.
+
+.. fieldlookup:: in
+
+in
+~~
+
+In a given list.
+
+Example::
+
+    Entry.objects.filter(id__in=[1, 3, 4])
+
+SQL equivalent::
+
+    SELECT ... WHERE id IN (1, 3, 4);
+
+You can also use a queryset to dynamically evaluate the list of values
+instead of providing a list of literal values::
+
+    inner_qs = Blog.objects.filter(name__contains='Cheddar')
+    entries = Entry.objects.filter(blog__in=inner_qs)
+
+This queryset will be evaluated as subselect statement::
+
+    SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')
+
+The above code fragment could also be written as follows::
+
+    inner_q = Blog.objects.filter(name__contains='Cheddar').values('pk').query
+    entries = Entry.objects.filter(blog__in=inner_q)
+
+
+.. versionchanged:: 1.1
+    In Django 1.0, only the latter piece of code is valid.
+
+This second form is a bit less readable and unnatural to write, since it
+accesses the internal ``query`` attribute and requires a ``ValuesQuerySet``.
+If your code doesn't require compatibility with Django 1.0, use the first
+form, passing in a queryset directly.
+
+If you pass in a ``ValuesQuerySet`` or ``ValuesListQuerySet`` (the result of
+calling ``values()`` or ``values_list()`` on a queryset) as the value to an
+``__in`` lookup, you need to ensure you are only extracting one field in the
+result. For example, this will work (filtering on the blog names)::
+
+    inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
+    entries = Entry.objects.filter(blog__name__in=inner_qs)
+
+This example will raise an exception, since the inner query is trying to
+extract two field values, where only one is expected::
+
+    # Bad code! Will raise a TypeError.
+    inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')
+    entries = Entry.objects.filter(blog__name__in=inner_qs)
+
+.. warning::
+
+    This ``query`` attribute should be considered an opaque internal attribute.
+    It's fine to use it like above, but its API may change between Django
+    versions.
+
+.. admonition:: Performance considerations
+
+    Be cautious about using nested queries and understand your database
+    server's performance characteristics (if in doubt, benchmark!). Some
+    database backends, most notably MySQL, don't optimize nested queries very
+    well. It is more efficient, in those cases, to extract a list of values
+    and then pass that into the second query. That is, execute two queries
+    instead of one::
+
+        values = Blog.objects.filter(
+                name__contains='Cheddar').values_list('pk', flat=True)
+        entries = Entry.objects.filter(blog__in=list(values))
+
+    Note the ``list()`` call around the Blog ``QuerySet`` to force execution of
+    the first query. Without it, a nested query would be executed, because
+    :ref:`querysets-are-lazy`.
+
+.. fieldlookup:: gt
+
+gt
+~~
+
+Greater than.
+
+Example::
+
+    Entry.objects.filter(id__gt=4)
+
+SQL equivalent::
+
+    SELECT ... WHERE id > 4;
+
+.. fieldlookup:: gte
+
+gte
+~~~
+
+Greater than or equal to.
+
+.. fieldlookup:: lt
+
+lt
+~~
+
+Less than.
+
+.. fieldlookup:: lte
+
+lte
+~~~
+
+Less than or equal to.
+
+.. fieldlookup:: startswith
+
+startswith
+~~~~~~~~~~
+
+Case-sensitive starts-with.
+
+Example::
+
+    Entry.objects.filter(headline__startswith='Will')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline LIKE 'Will%';
+
+SQLite doesn't support case-sensitive ``LIKE`` statements; ``startswith`` acts
+like ``istartswith`` for SQLite.
+
+.. fieldlookup:: istartswith
+
+istartswith
+~~~~~~~~~~~
+
+Case-insensitive starts-with.
+
+Example::
+
+    Entry.objects.filter(headline__istartswith='will')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline ILIKE 'Will%';
+
+.. admonition:: SQLite users
+
+    When using the SQLite backend and Unicode (non-ASCII) strings, bear in
+    mind the :ref:`database note <sqlite-string-matching>` about string
+    comparisons.
+
+.. fieldlookup:: endswith
+
+endswith
+~~~~~~~~
+
+Case-sensitive ends-with.
+
+Example::
+
+    Entry.objects.filter(headline__endswith='cats')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline LIKE '%cats';
+
+SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith`` acts
+like ``iendswith`` for SQLite.
+
+.. fieldlookup:: iendswith
+
+iendswith
+~~~~~~~~~
+
+Case-insensitive ends-with.
+
+Example::
+
+    Entry.objects.filter(headline__iendswith='will')
+
+SQL equivalent::
+
+    SELECT ... WHERE headline ILIKE '%will'
+
+.. admonition:: SQLite users
+
+    When using the SQLite backend and Unicode (non-ASCII) strings, bear in
+    mind the :ref:`database note <sqlite-string-matching>` about string
+    comparisons.
+
+.. fieldlookup:: range
+
+range
+~~~~~
+
+Range test (inclusive).
+
+Example::
+
+    start_date = datetime.date(2005, 1, 1)
+    end_date = datetime.date(2005, 3, 31)
+    Entry.objects.filter(pub_date__range=(start_date, end_date))
+
+SQL equivalent::
+
+    SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';
+
+You can use ``range`` anywhere you can use ``BETWEEN`` in SQL -- for dates,
+numbers and even characters.
+
+.. fieldlookup:: year
+
+year
+~~~~
+
+For date/datetime fields, exact year match. Takes a four-digit year.
+
+Example::
+
+    Entry.objects.filter(pub_date__year=2005)
+
+SQL equivalent::
+
+    SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005';
+
+(The exact SQL syntax varies for each database engine.)
+
+.. fieldlookup:: month
+
+month
+~~~~~
+
+For date/datetime fields, exact month match. Takes an integer 1 (January)
+through 12 (December).
+
+Example::
+
+    Entry.objects.filter(pub_date__month=12)
+
+SQL equivalent::
+
+    SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';
+
+(The exact SQL syntax varies for each database engine.)
+
+.. fieldlookup:: day
+
+day
+~~~
+
+For date/datetime fields, exact day match.
+
+Example::
+
+    Entry.objects.filter(pub_date__day=3)
+
+SQL equivalent::
+
+    SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';
+
+(The exact SQL syntax varies for each database engine.)
+
+Note this will match any record with a pub_date on the third day of the month,
+such as January 3, July 3, etc.
+
+.. fieldlookup:: week_day
+
+week_day
+~~~~~~~~
+
+.. versionadded:: 1.1
+
+For date/datetime fields, a 'day of the week' match.
+
+Takes an integer value representing the day of week from 1 (Sunday) to 7
+(Saturday).
+
+Example::
+
+    Entry.objects.filter(pub_date__week_day=2)
+
+(No equivalent SQL code fragment is included for this lookup because
+implementation of the relevant query varies among different database engines.)
+
+Note this will match any record with a pub_date that falls on a Monday (day 2
+of the week), regardless of the month or year in which it occurs. Week days
+are indexed with day 1 being Sunday and day 7 being Saturday.
+
+.. fieldlookup:: isnull
+
+isnull
+~~~~~~
+
+Takes either ``True`` or ``False``, which correspond to SQL queries of
+``IS NULL`` and ``IS NOT NULL``, respectively.
+
+Example::
+
+    Entry.objects.filter(pub_date__isnull=True)
+
+SQL equivalent::
+
+    SELECT ... WHERE pub_date IS NULL;
+
+.. fieldlookup:: search
+
+search
+~~~~~~
+
+A boolean full-text search, taking advantage of full-text indexing. This is
+like ``contains`` but is significantly faster due to full-text indexing.
+
+Example::
+
+    Entry.objects.filter(headline__search="+Django -jazz Python")
+
+SQL equivalent::
+
+    SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE);
+
+Note this is only available in MySQL and requires direct manipulation of the
+database to add the full-text index. By default Django uses BOOLEAN MODE for
+full text searches. `See the MySQL documentation for additional details.
+<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
+
+
+.. fieldlookup:: regex
+
+regex
+~~~~~
+
+.. versionadded:: 1.0
+
+Case-sensitive regular expression match.
+
+The regular expression syntax is that of the database backend in use.
+In the case of SQLite, which has no built in regular expression support,
+this feature is provided by a (Python) user-defined REGEXP function, and
+the regular expression syntax is therefore that of Python's ``re`` module.
+
+Example::
+
+    Entry.objects.get(title__regex=r'^(An?|The) +')
+
+SQL equivalents::
+
+    SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL
+
+    SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle
+
+    SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL
+
+    SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite
+
+Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the
+regular expression syntax is recommended.
+
+.. fieldlookup:: iregex
+
+iregex
+~~~~~~
+
+.. versionadded:: 1.0
+
+Case-insensitive regular expression match.
+
+Example::
+
+    Entry.objects.get(title__iregex=r'^(an?|the) +')
+
+SQL equivalents::
+
+    SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL
+
+    SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle
+
+    SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL
+
+    SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite
+
+.. _aggregation-functions:
+
+Aggregation Functions
+---------------------
+
+.. versionadded:: 1.1
+
+Django provides the following aggregation functions in the
+``django.db.models`` module. For details on how to use these
+aggregate functions, see
+:doc:`the topic guide on aggregation </topics/db/aggregation>`.
+
+Avg
+~~~
+
+.. class:: Avg(field)
+
+Returns the mean value of the given field.
+
+    * Default alias: ``<field>__avg``
+    * Return type: float
+
+Count
+~~~~~
+
+.. class:: Count(field, distinct=False)
+
+Returns the number of objects that are related through the provided field.
+
+    * Default alias: ``<field>__count``
+    * Return type: integer
+
+Has one optional argument:
+
+.. attribute:: distinct
+
+    If distinct=True, the count will only include unique instances. This has
+    the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
+
+Max
+~~~
+
+.. class:: Max(field)
+
+Returns the maximum value of the given field.
+
+    * Default alias: ``<field>__max``
+    * Return type: same as input field
+
+Min
+~~~
+
+.. class:: Min(field)
+
+Returns the minimum value of the given field.
+
+    * Default alias: ``<field>__min``
+    * Return type: same as input field
+
+StdDev
+~~~~~~
+
+.. class:: StdDev(field, sample=False)
+
+Returns the standard deviation of the data in the provided field.
+
+    * Default alias: ``<field>__stddev``
+    * Return type: float
+
+Has one optional argument:
+
+.. attribute:: sample
+
+    By default, ``StdDev`` returns the population standard deviation. However,
+    if ``sample=True``, the return value will be the sample standard deviation.
+
+.. admonition:: SQLite
+
+    SQLite doesn't provide ``StdDev`` out of the box. An implementation is
+    available as an extension module for SQLite. Consult the SQlite
+    documentation for instructions on obtaining and installing this extension.
+
+Sum
+~~~
+
+.. class:: Sum(field)
+
+Computes the sum of all values of the given field.
+
+    * Default alias: ``<field>__sum``
+    * Return type: same as input field
+
+Variance
+~~~~~~~~
+
+.. class:: Variance(field, sample=False)
+
+Returns the variance of the data in the provided field.
+
+    * Default alias: ``<field>__variance``
+    * Return type: float
+
+Has one optional argument:
+
+.. attribute:: sample
+
+    By default, ``Variance`` returns the population variance. However,
+    if ``sample=True``, the return value will be the sample variance.
+
+.. admonition:: SQLite
+
+    SQLite doesn't provide ``Variance`` out of the box. An implementation is
+    available as an extension module for SQLite. Consult the SQlite
+    documentation for instructions on obtaining and installing this extension.
diff --git a/parts/django/docs/ref/models/relations.txt b/parts/django/docs/ref/models/relations.txt
new file mode 100644
index 0000000..ee6bcdd
--- /dev/null
+++ b/parts/django/docs/ref/models/relations.txt
@@ -0,0 +1,105 @@
+=========================
+Related objects reference
+=========================
+
+.. currentmodule:: django.db.models.fields.related
+
+.. class:: RelatedManager
+
+    A "related manager" is a manager used in a one-to-many or many-to-many
+    related context. This happens in two cases:
+
+        * The "other side" of a :class:`~django.db.models.ForeignKey` relation.
+          That is::
+
+                class Reporter(models.Model):
+                    ...
+
+                class Article(models.Model):
+                    reporter = models.ForeignKey(Reporter)
+
+          In the above example, the methods below will be available on
+          the manager ``reporter.article_set``.
+
+        * Both sides of a :class:`~django.db.models.ManyToManyField` relation::
+
+                class Topping(models.Model):
+                    ...
+
+                class Pizza(models.Model):
+                    toppings = models.ManyToManyField(Topping)
+
+          In this example, the methods below will be available both on
+          ``topping.pizza_set`` and on ``pizza.toppings``.
+
+    These related managers have some extra methods:
+
+    .. method:: add(obj1, [obj2, ...])
+
+        Adds the specified model objects to the related object set.
+
+        Example::
+
+            >>> b = Blog.objects.get(id=1)
+            >>> e = Entry.objects.get(id=234)
+            >>> b.entry_set.add(e) # Associates Entry e with Blog b.
+
+    .. method:: create(**kwargs)
+
+        Creates a new object, saves it and puts it in the related object set.
+        Returns the newly created object::
+
+            >>> b = Blog.objects.get(id=1)
+            >>> e = b.entry_set.create(
+            ...     headline='Hello',
+            ...     body_text='Hi',
+            ...     pub_date=datetime.date(2005, 1, 1)
+            ... )
+
+            # No need to call e.save() at this point -- it's already been saved.
+
+        This is equivalent to (but much simpler than)::
+
+            >>> b = Blog.objects.get(id=1)
+            >>> e = Entry(
+            ...     blog=b,
+            ...     headline='Hello',
+            ...     body_text='Hi',
+            ...     pub_date=datetime.date(2005, 1, 1)
+            ... )
+            >>> e.save(force_insert=True)
+
+        Note that there's no need to specify the keyword argument of the model
+        that defines the relationship. In the above example, we don't pass the
+        parameter ``blog`` to ``create()``. Django figures out that the new
+        ``Entry`` object's ``blog`` field should be set to ``b``.
+
+    .. method:: remove(obj1, [obj2, ...])
+
+        Removes the specified model objects from the related object set::
+
+            >>> b = Blog.objects.get(id=1)
+            >>> e = Entry.objects.get(id=234)
+            >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
+
+        In order to prevent database inconsistency, this method only exists on
+        :class:`~django.db.models.ForeignKey` objects where ``null=True``. If
+        the related field can't be set to ``None`` (``NULL``), then an object
+        can't be removed from a relation without being added to another. In the
+        above example, removing ``e`` from ``b.entry_set()`` is equivalent to
+        doing ``e.blog = None``, and because the ``blog``
+        :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this
+        is invalid.
+
+    .. method:: clear()
+
+        Removes all objects from the related object set::
+
+            >>> b = Blog.objects.get(id=1)
+            >>> b.entry_set.clear()
+
+        Note this doesn't delete the related objects -- it just disassociates
+        them.
+
+        Just like ``remove()``, ``clear()`` is only available on
+        :class:`~django.db.models.ForeignKey`\s where ``null=True``.
diff --git a/parts/django/docs/ref/request-response.txt b/parts/django/docs/ref/request-response.txt
new file mode 100644
index 0000000..c663c1e
--- /dev/null
+++ b/parts/django/docs/ref/request-response.txt
@@ -0,0 +1,646 @@
+============================
+Request and response objects
+============================
+
+.. module:: django.http
+   :synopsis: Classes dealing with HTTP requests and responses.
+
+Quick overview
+==============
+
+Django uses request and response objects to pass state through the system.
+
+When a page is requested, Django creates an :class:`HttpRequest` object that
+contains metadata about the request. Then Django loads the appropriate view,
+passing the :class:`HttpRequest` as the first argument to the view function.
+Each view is responsible for returning an :class:`HttpResponse` object.
+
+This document explains the APIs for :class:`HttpRequest` and
+:class:`HttpResponse` objects.
+
+HttpRequest objects
+===================
+
+.. class:: HttpRequest
+
+Attributes
+----------
+
+All attributes except ``session`` should be considered read-only.
+
+.. attribute:: HttpRequest.path
+
+    A string representing the full path to the requested page, not including
+    the domain.
+
+    Example: ``"/music/bands/the_beatles/"``
+
+.. attribute:: HttpRequest.path_info
+
+    Under some web server configurations, the portion of the URL after the host
+    name is split up into a script prefix portion and a path info portion
+    (this happens, for example, when using the ``django.root`` option
+    with the :ref:`modpython handler from Apache <howto-deployment-modpython>`).
+    The ``path_info`` attribute always contains the path info portion of the
+    path, no matter what web server is being used. Using this instead of
+    attr:`~HttpRequest.path` can make your code much easier to move between test
+    and deployment servers.
+
+    For example, if the ``django.root`` for your application is set to 
+    ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"``
+    and ``path_info`` would be ``"/music/bands/the_beatles/"``.
+
+.. attribute:: HttpRequest.method
+
+    A string representing the HTTP method used in the request. This is
+    guaranteed to be uppercase. Example::
+
+        if request.method == 'GET':
+            do_something()
+        elif request.method == 'POST':
+            do_something_else()
+
+.. attribute:: HttpRequest.encoding
+
+    A string representing the current encoding used to decode form submission
+    data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is
+    used). You can write to this attribute to change the encoding used when
+    accessing the form data. Any subsequent attribute accesses (such as reading
+    from ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if
+    you know the form data is not in the :setting:`DEFAULT_CHARSET` encoding.
+
+.. attribute:: HttpRequest.GET
+
+    A dictionary-like object containing all given HTTP GET parameters. See the
+    :class:`QueryDict` documentation below.
+
+.. attribute:: HttpRequest.POST
+
+    A dictionary-like object containing all given HTTP POST parameters. See the
+    :class:`QueryDict` documentation below.
+
+    It's possible that a request can come in via POST with an empty ``POST``
+    dictionary -- if, say, a form is requested via the POST HTTP method but
+    does not include form data. Therefore, you shouldn't use ``if request.POST``
+    to check for use of the POST method; instead, use ``if request.method ==
+    "POST"`` (see above).
+
+    Note: ``POST`` does *not* include file-upload information. See ``FILES``.
+
+.. attribute:: HttpRequest.REQUEST
+
+    For convenience, a dictionary-like object that searches ``POST`` first,
+    then ``GET``. Inspired by PHP's ``$_REQUEST``.
+
+    For example, if ``GET = {"name": "john"}`` and ``POST = {"age": '34'}``,
+    ``REQUEST["name"]`` would be ``"john"``, and ``REQUEST["age"]`` would be
+    ``"34"``.
+
+    It's strongly suggested that you use ``GET`` and ``POST`` instead of
+    ``REQUEST``, because the former are more explicit.
+
+.. attribute:: HttpRequest.COOKIES
+
+    A standard Python dictionary containing all cookies. Keys and values are
+    strings.
+
+.. attribute:: HttpRequest.FILES
+
+    A dictionary-like object containing all uploaded files. Each key in
+    ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each
+    value in ``FILES`` is an :class:`UploadedFile` as described below.
+
+    See :doc:`/topics/files` for more information.
+
+    Note that ``FILES`` will only contain data if the request method was POST
+    and the ``<form>`` that posted to the request had
+    ``enctype="multipart/form-data"``. Otherwise, ``FILES`` will be a blank
+    dictionary-like object.
+
+    .. versionchanged:: 1.0
+
+    In previous versions of Django, ``request.FILES`` contained simple ``dict``
+    objects representing uploaded files. This is no longer true -- files are
+    represented by :class:`UploadedFile` objects.
+
+    These :class:`UploadedFile` objects will emulate the old-style ``dict``
+    interface, but this is deprecated and will be removed in the next release
+    of Django.
+
+.. attribute:: HttpRequest.META
+
+    A standard Python dictionary containing all available HTTP headers.
+    Available headers depend on the client and server, but here are some
+    examples:
+
+        * ``CONTENT_LENGTH``
+        * ``CONTENT_TYPE``
+        * ``HTTP_ACCEPT_ENCODING``
+        * ``HTTP_ACCEPT_LANGUAGE``
+        * ``HTTP_HOST`` -- The HTTP Host header sent by the client.
+        * ``HTTP_REFERER`` -- The referring page, if any.
+        * ``HTTP_USER_AGENT`` -- The client's user-agent string.
+        * ``QUERY_STRING`` -- The query string, as a single (unparsed) string.
+        * ``REMOTE_ADDR`` -- The IP address of the client.
+        * ``REMOTE_HOST`` -- The hostname of the client.
+        * ``REMOTE_USER`` -- The user authenticated by the Web server, if any.
+        * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``.
+        * ``SERVER_NAME`` -- The hostname of the server.
+        * ``SERVER_PORT`` -- The port of the server.
+
+    With the exception of ``CONTENT_LENGTH`` and ``CONTENT_TYPE``, as given
+    above, any HTTP headers in the request are converted to ``META`` keys by
+    converting all characters to uppercase, replacing any hyphens with
+    underscores and adding an ``HTTP_`` prefix to the name. So, for example, a
+    header called ``X-Bender`` would be mapped to the ``META`` key
+    ``HTTP_X_BENDER``.
+
+.. attribute:: HttpRequest.user
+
+    A ``django.contrib.auth.models.User`` object representing the currently
+    logged-in user. If the user isn't currently logged in, ``user`` will be set
+    to an instance of ``django.contrib.auth.models.AnonymousUser``. You
+    can tell them apart with ``is_authenticated()``, like so::
+
+        if request.user.is_authenticated():
+            # Do something for logged-in users.
+        else:
+            # Do something for anonymous users.
+
+    ``user`` is only available if your Django installation has the
+    ``AuthenticationMiddleware`` activated. For more, see
+    :doc:`/topics/auth`.
+
+.. attribute:: HttpRequest.session
+
+    A readable-and-writable, dictionary-like object that represents the current
+    session. This is only available if your Django installation has session
+    support activated. See the :doc:`session documentation
+    </topics/http/sessions>` for full details.
+
+.. attribute:: HttpRequest.raw_post_data
+
+    The raw HTTP POST data. This is only useful for advanced processing. Use
+    ``POST`` instead.
+
+.. attribute:: HttpRequest.urlconf
+
+    Not defined by Django itself, but will be read if other code (e.g., a custom
+    middleware class) sets it. When present, this will be used as the root
+    URLconf for the current request, overriding the :setting:`ROOT_URLCONF`
+    setting. See :ref:`how-django-processes-a-request` for details.
+
+Methods
+-------
+
+.. method:: HttpRequest.get_host()
+
+    Returns the originating host of the request using information from the
+    ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If
+    they don't provide a value, the method uses a combination of
+    ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_.
+
+    .. _PEP 333: http://www.python.org/dev/peps/pep-0333/
+
+    Example: ``"127.0.0.1:8000"``
+
+    .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is
+        behind multiple proxies. One solution is to use middleware to rewrite
+        the proxy headers, as in the following example::
+
+            class MultipleProxyMiddleware(object):
+                FORWARDED_FOR_FIELDS = [
+                    'HTTP_X_FORWARDED_FOR',
+                    'HTTP_X_FORWARDED_HOST',
+                    'HTTP_X_FORWARDED_SERVER',
+                ]
+
+                def process_request(self, request):
+                    """
+                    Rewrites the proxy headers so that only the most
+                    recent proxy is used.
+                    """
+                    for field in self.FORWARDED_FOR_FIELDS:
+                        if field in request.META:
+                            if ',' in request.META[field]:
+                                parts = request.META[field].split(',')
+                                request.META[field] = parts[-1].strip()
+
+
+.. method:: HttpRequest.get_full_path()
+
+   Returns the ``path``, plus an appended query string, if applicable.
+
+   Example: ``"/music/bands/the_beatles/?print=true"``
+
+.. method:: HttpRequest.build_absolute_uri(location)
+
+   Returns the absolute URI form of ``location``. If no location is provided,
+   the location will be set to ``request.get_full_path()``.
+
+   If the location is already an absolute URI, it will not be altered.
+   Otherwise the absolute URI is built using the server variables available in
+   this request.
+
+   Example: ``"http://example.com/music/bands/the_beatles/?print=true"``
+
+.. method:: HttpRequest.is_secure()
+
+   Returns ``True`` if the request is secure; that is, if it was made with
+   HTTPS.
+
+.. method:: HttpRequest.is_ajax()
+
+   Returns ``True`` if the request was made via an ``XMLHttpRequest``, by
+   checking the ``HTTP_X_REQUESTED_WITH`` header for the string
+   ``'XMLHttpRequest'``. Most modern JavaScript libraries send this header.
+   If you write your own XMLHttpRequest call (on the browser side), you'll
+   have to set this header manually if you want ``is_ajax()`` to work.
+
+
+UploadedFile objects
+====================
+
+.. class:: UploadedFile
+
+
+Attributes
+----------
+
+.. attribute::  UploadedFile.name
+
+    The name of the uploaded file.
+
+.. attribute:: UploadedFile.size
+
+    The size, in bytes, of the uploaded file.
+
+Methods
+----------
+
+.. method:: UploadedFile.chunks(chunk_size=None)
+
+    Returns a generator that yields sequential chunks of data.
+
+.. method:: UploadedFile.read(num_bytes=None)
+
+    Read a number of bytes from the file.
+
+
+
+QueryDict objects
+=================
+
+.. class:: QueryDict
+
+In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances
+of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like
+class customized to deal with multiple values for the same key. This is
+necessary because some HTML form elements, notably
+``<select multiple="multiple">``, pass multiple values for the same key.
+
+``QueryDict`` instances are immutable, unless you create a ``copy()`` of them.
+That means you can't change attributes of ``request.POST`` and ``request.GET``
+directly.
+
+Methods
+-------
+
+:class:`QueryDict` implements all the standard dictionary methods, because it's
+a subclass of dictionary. Exceptions are outlined here:
+
+.. method:: QueryDict.__getitem__(key)
+
+    Returns the value for the given key. If the key has more than one value,
+    ``__getitem__()`` returns the last value. Raises
+    ``django.utils.datastructures.MultiValueDictKeyError`` if the key does not
+    exist. (This is a subclass of Python's standard ``KeyError``, so you can
+    stick to catching ``KeyError``.)
+
+.. method:: QueryDict.__setitem__(key, value)
+
+    Sets the given key to ``[value]`` (a Python list whose single element is
+    ``value``). Note that this, as other dictionary functions that have side
+    effects, can only be called on a mutable ``QueryDict`` (one that was created
+    via ``copy()``).
+
+.. method:: QueryDict.__contains__(key)
+
+    Returns ``True`` if the given key is set. This lets you do, e.g., ``if "foo"
+    in request.GET``.
+
+.. method:: QueryDict.get(key, default)
+
+    Uses the same logic as ``__getitem__()`` above, with a hook for returning a
+    default value if the key doesn't exist.
+
+.. method:: QueryDict.setdefault(key, default)
+
+    Just like the standard dictionary ``setdefault()`` method, except it uses
+    ``__setitem__()`` internally.
+
+.. method:: QueryDict.update(other_dict)
+
+    Takes either a ``QueryDict`` or standard dictionary. Just like the standard
+    dictionary ``update()`` method, except it *appends* to the current
+    dictionary items rather than replacing them. For example::
+
+          >>> q = QueryDict('a=1')
+          >>> q = q.copy() # to make it mutable
+          >>> q.update({'a': '2'})
+          >>> q.getlist('a')
+          [u'1', u'2']
+          >>> q['a'] # returns the last
+          [u'2']
+
+.. method:: QueryDict.items()
+
+    Just like the standard dictionary ``items()`` method, except this uses the
+    same last-value logic as ``__getitem__()``. For example::
+
+           >>> q = QueryDict('a=1&a=2&a=3')
+           >>> q.items()
+           [(u'a', u'3')]
+
+.. method:: QueryDict.iteritems()
+
+    Just like the standard dictionary ``iteritems()`` method. Like
+    :meth:`QueryDict.items()` this uses the same last-value logic as
+    :meth:`QueryDict.__getitem__()`.
+
+.. method:: QueryDict.iterlists()
+
+    Like :meth:`QueryDict.iteritems()` except it includes all values, as a list,
+    for each member of the dictionary.
+
+.. method:: QueryDict.values()
+
+    Just like the standard dictionary ``values()`` method, except this uses the
+    same last-value logic as ``__getitem__()``. For example::
+
+           >>> q = QueryDict('a=1&a=2&a=3')
+           >>> q.values()
+           [u'3']
+
+.. method:: QueryDict.itervalues()
+
+    Just like :meth:`QueryDict.values()`, except an iterator.
+
+In addition, ``QueryDict`` has the following methods:
+
+.. method:: QueryDict.copy()
+
+    Returns a copy of the object, using ``copy.deepcopy()`` from the Python
+    standard library. The copy will be mutable -- that is, you can change its
+    values.
+
+.. method:: QueryDict.getlist(key)
+
+    Returns the data with the requested key, as a Python list. Returns an
+    empty list if the key doesn't exist. It's guaranteed to return a list of
+    some sort.
+
+.. method:: QueryDict.setlist(key, list_)
+
+    Sets the given key to ``list_`` (unlike ``__setitem__()``).
+
+.. method:: QueryDict.appendlist(key, item)
+
+    Appends an item to the internal list associated with key.
+
+.. method:: QueryDict.setlistdefault(key, default_list)
+
+    Just like ``setdefault``, except it takes a list of values instead of a
+    single value.
+
+.. method:: QueryDict.lists()
+
+    Like :meth:`items()`, except it includes all values, as a list, for each
+    member of the dictionary. For example::
+
+         >>> q = QueryDict('a=1&a=2&a=3')
+         >>> q.lists()
+         [(u'a', [u'1', u'2', u'3'])]
+
+.. method:: QueryDict.urlencode()
+
+    Returns a string of the data in query-string format.
+    Example: ``"a=2&b=3&b=5"``.
+
+HttpResponse objects
+====================
+
+.. class:: HttpResponse
+
+In contrast to :class:`HttpRequest` objects, which are created automatically by
+Django, :class:`HttpResponse` objects are your responsibility. Each view you
+write is responsible for instantiating, populating and returning an
+:class:`HttpResponse`.
+
+The :class:`HttpResponse` class lives in the :mod:`django.http` module.
+
+Usage
+-----
+
+Passing strings
+~~~~~~~~~~~~~~~
+
+Typical usage is to pass the contents of the page, as a string, to the
+:class:`HttpResponse` constructor::
+
+    >>> response = HttpResponse("Here's the text of the Web page.")
+    >>> response = HttpResponse("Text only, please.", mimetype="text/plain")
+
+But if you want to add content incrementally, you can use ``response`` as a
+file-like object::
+
+    >>> response = HttpResponse()
+    >>> response.write("<p>Here's the text of the Web page.</p>")
+    >>> response.write("<p>Here's another paragraph.</p>")
+
+Passing iterators
+~~~~~~~~~~~~~~~~~
+
+Finally, you can pass ``HttpResponse`` an iterator rather than passing it
+hard-coded strings. If you use this technique, follow these guidelines:
+
+    * The iterator should return strings.
+    * If an :class:`HttpResponse` has been initialized with an iterator as its
+      content, you can't use the class:`HttpResponse` instance as a file-like
+      object. Doing so will raise ``Exception``.
+
+Setting headers
+~~~~~~~~~~~~~~~
+
+To set or remove a header in your response, treat it like a dictionary::
+
+    >>> response = HttpResponse()
+    >>> response['Cache-Control'] = 'no-cache'
+    >>> del response['Cache-Control']
+
+Note that unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header
+doesn't exist.
+
+.. versionadded:: 1.1
+
+HTTP headers cannot contain newlines. An attempt to set a header containing a
+newline character (CR or LF) will raise ``BadHeaderError``
+
+Telling the browser to treat the response as a file attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To tell the browser to treat the response as a file attachment, use the
+``mimetype`` argument and set the ``Content-Disposition`` header. For example,
+this is how you might return a Microsoft Excel spreadsheet::
+
+    >>> response = HttpResponse(my_data, mimetype='application/vnd.ms-excel')
+    >>> response['Content-Disposition'] = 'attachment; filename=foo.xls'
+
+There's nothing Django-specific about the ``Content-Disposition`` header, but
+it's easy to forget the syntax, so we've included it here.
+
+Attributes
+----------
+
+.. attribute:: HttpResponse.content
+
+    A normal Python string representing the content, encoded from a Unicode
+    object if necessary.
+
+.. attribute:: HttpResponse.status_code
+
+    The `HTTP Status code`_ for the response.
+
+Methods
+-------
+
+.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
+
+    Instantiates an ``HttpResponse`` object with the given page content (a
+    string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is
+    ``'text/html'``.
+
+    ``content`` can be an iterator or a string. If it's an iterator, it should
+    return strings, and those strings will be joined together to form the
+    content of the response.
+
+    ``status`` is the `HTTP Status code`_ for the response.
+
+    ``content_type`` is an alias for ``mimetype``. Historically, this parameter
+    was only called ``mimetype``, but since this is actually the value included
+    in the HTTP ``Content-Type`` header, it can also include the character set
+    encoding, which makes it more than just a MIME type specification.
+    If ``mimetype`` is specified (not ``None``), that value is used.
+    Otherwise, ``content_type`` is used. If neither is given, the
+    :setting:`DEFAULT_CONTENT_TYPE` setting is used.
+
+.. method:: HttpResponse.__setitem__(header, value)
+
+    Sets the given header name to the given value. Both ``header`` and
+    ``value`` should be strings.
+
+.. method:: HttpResponse.__delitem__(header)
+
+    Deletes the header with the given name. Fails silently if the header
+    doesn't exist. Case-insensitive.
+
+.. method:: HttpResponse.__getitem__(header)
+
+    Returns the value for the given header name. Case-insensitive.
+
+.. method:: HttpResponse.has_header(header)
+
+    Returns ``True`` or ``False`` based on a case-insensitive check for a
+    header with the given name.
+
+.. method:: HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None)
+
+    Sets a cookie. The parameters are the same as in the `cookie Morsel`_
+    object in the Python standard library.
+
+        * ``max_age`` should be a number of seconds, or ``None`` (default) if
+          the cookie should last only as long as the client's browser session.
+        * ``expires`` should be a string in the format
+          ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``.
+        * Use ``domain`` if you want to set a cross-domain cookie. For example,
+          ``domain=".lawrence.com"`` will set a cookie that is readable by
+          the domains www.lawrence.com, blogs.lawrence.com and
+          calendars.lawrence.com. Otherwise, a cookie will only be readable by
+          the domain that set it.
+
+    .. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel
+
+.. method:: HttpResponse.delete_cookie(key, path='/', domain=None)
+
+    Deletes the cookie with the given key. Fails silently if the key doesn't
+    exist.
+
+    Due to the way cookies work, ``path`` and ``domain`` should be the same
+    values you used in ``set_cookie()`` -- otherwise the cookie may not be
+    deleted.
+
+.. method:: HttpResponse.write(content)
+
+    This method makes an :class:`HttpResponse` instance a file-like object.
+
+.. method:: HttpResponse.flush()
+
+    This method makes an :class:`HttpResponse` instance a file-like object.
+
+.. method:: HttpResponse.tell()
+
+    This method makes an :class:`HttpResponse` instance a file-like object.
+
+.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
+
+
+.. _ref-httpresponse-subclasses:
+
+HttpResponse subclasses
+-----------------------
+
+Django includes a number of ``HttpResponse`` subclasses that handle different
+types of HTTP responses. Like ``HttpResponse``, these subclasses live in
+:mod:`django.http`.
+
+.. class:: HttpResponseRedirect
+
+    The constructor takes a single argument -- the path to redirect to. This
+    can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or
+    an absolute path with no domain (e.g. ``'/search/'``). Note that this
+    returns an HTTP status code 302.
+
+.. class:: HttpResponsePermanentRedirect
+
+    Like :class:`HttpResponseRedirect`, but it returns a permanent redirect
+    (HTTP status code 301) instead of a "found" redirect (status code 302).
+
+.. class:: HttpResponseNotModified
+
+    The constructor doesn't take any arguments. Use this to designate that a
+    page hasn't been modified since the user's last request (status code 304).
+
+.. class:: HttpResponseBadRequest
+
+    Acts just like :class:`HttpResponse` but uses a 400 status code.
+
+.. class:: HttpResponseNotFound
+
+    Acts just like :class:`HttpResponse` but uses a 404 status code.
+
+.. class:: HttpResponseForbidden
+
+    Acts just like :class:`HttpResponse` but uses a 403 status code.
+
+.. class:: HttpResponseNotAllowed
+
+    Like :class:`HttpResponse`, but uses a 405 status code. Takes a single,
+    required argument: a list of permitted methods (e.g. ``['GET', 'POST']``).
+
+.. class:: HttpResponseGone
+
+    Acts just like :class:`HttpResponse` but uses a 410 status code.
+
+.. class:: HttpResponseServerError
+
+    Acts just like :class:`HttpResponse` but uses a 500 status code.
diff --git a/parts/django/docs/ref/settings.txt b/parts/django/docs/ref/settings.txt
new file mode 100644
index 0000000..ab1f28c
--- /dev/null
+++ b/parts/django/docs/ref/settings.txt
@@ -0,0 +1,1836 @@
+========
+Settings
+========
+
+.. contents::
+    :local:
+    :depth: 1
+
+Available settings
+==================
+
+Here's a full list of all available settings, in alphabetical order, and their
+default values.
+
+.. setting:: ABSOLUTE_URL_OVERRIDES
+
+ABSOLUTE_URL_OVERRIDES
+----------------------
+
+Default: ``{}`` (Empty dictionary)
+
+A dictionary mapping ``"app_label.model_name"`` strings to functions that take
+a model object and return its URL. This is a way of overriding
+``get_absolute_url()`` methods on a per-installation basis. Example::
+
+    ABSOLUTE_URL_OVERRIDES = {
+        'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,
+        'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
+    }
+
+Note that the model name used in this setting should be all lower-case, regardless
+of the case of the actual model class name.
+
+.. setting:: ADMIN_FOR
+
+ADMIN_FOR
+---------
+
+Default: ``()`` (Empty tuple)
+
+Used for admin-site settings modules, this should be a tuple of settings
+modules (in the format ``'foo.bar.baz'``) for which this site is an admin.
+
+The admin site uses this in its automatically-introspected documentation of
+models, views and template tags.
+
+.. setting:: ADMIN_MEDIA_PREFIX
+
+ADMIN_MEDIA_PREFIX
+------------------
+
+Default: ``'/media/'``
+
+The URL prefix for admin media -- CSS, JavaScript and images used by
+the Django administrative interface. Make sure to use a trailing
+slash, and to have this be different from the ``MEDIA_URL`` setting
+(since the same URL cannot be mapped onto two different sets of
+files).
+
+.. setting:: ADMINS
+
+ADMINS
+------
+
+Default: ``()`` (Empty tuple)
+
+A tuple that lists people who get code error notifications. When
+``DEBUG=False`` and a view raises an exception, Django will e-mail these people
+with the full exception information. Each member of the tuple should be a tuple
+of (Full name, e-mail address). Example::
+
+    (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
+
+Note that Django will e-mail *all* of these people whenever an error happens.
+See :doc:`/howto/error-reporting` for more information.
+
+.. setting:: ALLOWED_INCLUDE_ROOTS
+
+ALLOWED_INCLUDE_ROOTS
+---------------------
+
+Default: ``()`` (Empty tuple)
+
+A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template
+tag. This is a security measure, so that template authors can't access files
+that they shouldn't be accessing.
+
+For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``,
+then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}``
+wouldn't.
+
+.. setting:: APPEND_SLASH
+
+APPEND_SLASH
+------------
+
+Default: ``True``
+
+When set to ``True``, if the request URL does not match any of the patterns
+in the URLconf and it doesn't end in a slash, an HTTP redirect is issued to the
+same URL with a slash appended. Note that the redirect may cause any data
+submitted in a POST request to be lost.
+
+The ``APPEND_SLASH`` setting is only used if
+:class:`~django.middleware.common.CommonMiddleware` is installed
+(see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`.
+
+.. setting:: AUTHENTICATION_BACKENDS
+
+AUTHENTICATION_BACKENDS
+-----------------------
+
+Default: ``('django.contrib.auth.backends.ModelBackend',)``
+
+A tuple of authentication backend classes (as strings) to use when attempting to
+authenticate a user. See the :doc:`authentication backends documentation
+</ref/authbackends>` for details.
+
+.. setting:: AUTH_PROFILE_MODULE
+
+AUTH_PROFILE_MODULE
+-------------------
+
+Default: Not defined
+
+The site-specific user profile model used by this site. See
+:ref:`auth-profiles`.
+
+.. setting:: CACHE_BACKEND
+
+CACHE_BACKEND
+-------------
+
+Default: ``'locmem://'``
+
+The cache backend to use. See :doc:`/topics/cache`.
+
+.. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY
+
+CACHE_MIDDLEWARE_ANONYMOUS_ONLY
+-------------------------------
+
+Default: ``False``
+
+If the value of this setting is ``True``, only anonymous requests (i.e., not
+those made by a logged-in user) will be cached.  Otherwise, the middleware
+caches every page that doesn't have GET or POST parameters.
+
+If you set the value of this setting to ``True``, you should make sure you've
+activated ``AuthenticationMiddleware``.
+
+See the :doc:`cache documentation </topics/cache>` for more information.
+
+.. setting:: CACHE_MIDDLEWARE_KEY_PREFIX
+
+CACHE_MIDDLEWARE_KEY_PREFIX
+---------------------------
+
+Default: ``''`` (Empty string)
+
+The cache key prefix that the cache middleware should use. See
+:doc:`/topics/cache`.
+
+.. setting:: CACHE_MIDDLEWARE_SECONDS
+
+CACHE_MIDDLEWARE_SECONDS
+------------------------
+
+Default: ``600``
+
+The default number of seconds to cache a page when the caching middleware or
+``cache_page()`` decorator is used.
+
+.. setting:: CSRF_COOKIE_DOMAIN
+
+CSRF_COOKIE_DOMAIN
+------------------
+
+.. versionadded:: 1.2
+
+Default: ``None``
+
+The domain to be used when setting the CSRF cookie.  This can be useful for
+allowing cross-subdomain requests to be exluded from the normal cross site
+request forgery protection.  It should be set to a string such as
+``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
+accepted by accepted by a view served from another subdomain.
+
+.. setting:: CSRF_COOKIE_NAME
+
+CSRF_COOKIE_NAME
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``'csrftoken'``
+
+The name of the cookie to use for the CSRF authentication token. This can be whatever you
+want.  See :doc:`/ref/contrib/csrf`.
+
+.. setting:: CSRF_FAILURE_VIEW
+
+CSRF_FAILURE_VIEW
+-----------------
+
+.. versionadded:: 1.2
+
+Default: ``'django.views.csrf.csrf_failure'``
+
+A dotted path to the view function to be used when an incoming request
+is rejected by the CSRF protection.  The function should have this signature::
+
+  def csrf_failure(request, reason="")
+
+where ``reason`` is a short message (intended for developers or logging, not for
+end users) indicating the reason the request was rejected.  See
+:doc:`/ref/contrib/csrf`.
+
+
+.. setting:: DATABASES
+
+DATABASES
+---------
+
+.. versionadded:: 1.2
+
+Default: ``{}`` (Empty dictionary)
+
+A dictionary containing the settings for all databases to be used with
+Django. It is a nested dictionary whose contents maps database aliases
+to a dictionary containing the options for an individual database.
+
+The :setting:`DATABASES` setting must configure a ``default`` database;
+any number of additional databases may also be specified.
+
+The simplest possible settings file is for a single-database setup using
+SQLite. This can be configured using the following::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.sqlite3',
+            'NAME': 'mydatabase'
+        }
+    }
+
+For other database backends, or more complex SQLite configurations, other options
+will be required. The following inner options are available.
+
+.. setting:: ENGINE
+
+ENGINE
+~~~~~~
+
+Default: ``''`` (Empty string)
+
+The database backend to use. The built-in database backends are:
+
+    * ``'django.db.backends.postgresql_psycopg2'``
+    * ``'django.db.backends.postgresql'``
+    * ``'django.db.backends.mysql'``
+    * ``'django.db.backends.sqlite3'``
+    * ``'django.db.backends.oracle'``
+
+You can use a database backend that doesn't ship with Django by setting
+``ENGINE`` to a fully-qualified path (i.e.
+``mypackage.backends.whatever``). Writing a whole new database backend from
+scratch is left as an exercise to the reader; see the other backends for
+examples.
+
+.. note::
+    Prior to Django 1.2, you could use a short version of the backend name
+    to reference the built-in database backends (e.g., you could use
+    ``'sqlite3'`` to refer to the SQLite backend). This format has been
+    deprecated, and will be removed in Django 1.4.
+
+.. setting:: HOST
+
+HOST
+~~~~
+
+Default: ``''`` (Empty string)
+
+Which host to use when connecting to the database. An empty string means
+localhost. Not used with SQLite.
+
+If this value starts with a forward slash (``'/'``) and you're using MySQL,
+MySQL will connect via a Unix socket to the specified socket. For example::
+
+    "HOST": '/var/run/mysql'
+
+If you're using MySQL and this value *doesn't* start with a forward slash, then
+this value is assumed to be the host.
+
+If you're using PostgreSQL, an empty string means to use a Unix domain socket
+for the connection, rather than a network connection to localhost. If you
+explicitly need to use a TCP/IP connection on the local machine with
+PostgreSQL, specify ``localhost`` here.
+
+.. setting:: NAME
+
+NAME
+~~~~
+
+Default: ``''`` (Empty string)
+
+The name of the database to use. For SQLite, it's the full path to the database
+file. When specifying the path, always use forward slashes, even on Windows
+(e.g. ``C:/homes/user/mysite/sqlite3.db``).
+
+.. setting:: OPTIONS
+
+OPTIONS
+~~~~~~~
+
+Default: ``{}`` (Empty dictionary)
+
+Extra parameters to use when connecting to the database. Available parameters
+vary depending on your database backend.
+
+Some information on available parameters can be found in the
+:doc:`Database Backends </ref/databases>` documentation. For more information,
+consult your backend module's own documentation.
+
+.. setting:: PASSWORD
+
+PASSWORD
+~~~~~~~~
+
+Default: ``''`` (Empty string)
+
+The password to use when connecting to the database. Not used with SQLite.
+
+.. setting:: PORT
+
+PORT
+~~~~
+
+Default: ``''`` (Empty string)
+
+The port to use when connecting to the database. An empty string means the
+default port. Not used with SQLite.
+
+.. setting:: USER
+
+USER
+~~~~
+
+Default: ``''`` (Empty string)
+
+The username to use when connecting to the database. Not used with SQLite.
+
+.. setting:: TEST_CHARSET
+
+TEST_CHARSET
+~~~~~~~~~~~~
+
+Default: ``None``
+
+The character set encoding used to create the test database. The value of this
+string is passed directly through to the database, so its format is
+backend-specific.
+
+Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and
+MySQL_ (``mysql``) backends.
+
+.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
+.. _MySQL: http://dev.mysql.com/doc/refman/5.0/en/charset-database.html
+
+.. setting:: TEST_COLLATION
+
+TEST_COLLATION
+~~~~~~~~~~~~~~
+
+Default: ``None``
+
+The collation order to use when creating the test database. This value is
+passed directly to the backend, so its format is backend-specific.
+
+Only supported for the ``mysql`` backend (see the `MySQL manual`_ for details).
+
+.. _MySQL manual: MySQL_
+
+.. setting:: TEST_DEPENDENCIES
+
+TEST_DEPENDENCIES
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2.4
+
+Default: ``['default']``, for all databases other than ``default``,
+which has no dependencies.
+
+The creation-order dependencies of the database. See the documentation
+on :ref:`controlling the creation order of test databases
+<topics-testing-creation-dependencies>` for details.
+
+.. setting:: TEST_MIRROR
+
+TEST_MIRROR
+~~~~~~~~~~~
+
+Default: ``None``
+
+The alias of the database that this database should mirror during
+testing.
+
+This setting exists to allow for testing of master/slave
+configurations of multiple databases. See the documentation on
+:ref:`testing master/slave configurations
+<topics-testing-masterslave>` for details.
+
+.. setting:: TEST_NAME
+
+TEST_NAME
+~~~~~~~~~
+
+Default: ``None``
+
+The name of database to use when running the test suite.
+
+If the default value (``None``) is used with the SQLite database engine, the
+tests will use a memory resident database. For all other database engines the
+test database will use the name ``'test_' + DATABASE_NAME``.
+
+See :doc:`/topics/testing`.
+
+.. setting:: TEST_USER
+
+TEST_USER
+~~~~~~~~~
+
+Default: ``None``
+
+This is an Oracle-specific setting.
+
+The username to use when connecting to the Oracle database that will be used
+when running tests.
+
+.. setting:: DATABASE_ROUTERS
+
+DATABASE_ROUTERS
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``[]`` (Empty list)
+
+The list of routers that will be used to determine which database
+to use when performing a database queries.
+
+See the documentation on :ref:`automatic database routing in multi
+database configurations <topics-db-multi-db-routing>`.
+
+.. setting:: DATE_FORMAT
+
+DATE_FORMAT
+-----------
+
+Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``)
+
+The default formatting to use for displaying date fields in any part of the
+system. Note that if :setting:`USE_L10N` is set to ``True``, then the
+locale-dictated format has higher precedence and will be applied instead. See
+:tfilter:`allowed date format strings <date>`.
+
+.. versionchanged:: 1.2
+    This setting can now be overriden by setting ``USE_L10N`` to ``True``.
+
+See also ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATE_FORMAT``.
+
+.. setting:: DATE_INPUT_FORMATS
+
+DATE_INPUT_FORMATS
+------------------
+
+.. versionadded:: 1.2
+
+Default::
+
+    ('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y',
+    '%b %d, %Y', '%d %b %Y', '%d %b, %Y', '%B %d %Y',
+    '%B %d, %Y', '%d %B %Y', '%d %B, %Y')
+
+A tuple of formats that will be accepted when inputting data on a date
+field. Formats will be tried in order, using the first valid.
+Note that these format strings are specified in Python's datetime_ module
+syntax, that is different from the one used by Django for formatting dates
+to be displayed.
+
+See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``.
+
+.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+
+.. setting:: DATETIME_FORMAT
+
+DATETIME_FORMAT
+---------------
+
+Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``)
+
+The default formatting to use for displaying datetime fields in any part of the
+system. Note that if :setting:`USE_L10N` is set to ``True``, then the
+locale-dictated format has higher precedence and will be applied instead. See
+:tfilter:`allowed date format strings <date>`.
+
+.. versionchanged:: 1.2
+    This setting can now be overriden by setting ``USE_L10N`` to ``True``.
+
+See also ``DATE_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
+
+.. setting:: DATETIME_INPUT_FORMATS
+
+DATETIME_INPUT_FORMATS
+----------------------
+
+.. versionadded:: 1.2
+
+Default::
+
+    ('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d',
+    '%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y',
+    '%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y')
+
+A tuple of formats that will be accepted when inputting data on a datetime
+field. Formats will be tried in order, using the first valid.
+Note that these format strings are specified in Python's datetime_ module
+syntax, that is different from the one used by Django for formatting dates
+to be displayed.
+
+See also ``DATE_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``.
+
+.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+
+.. setting:: DEBUG
+
+DEBUG
+-----
+
+Default: ``False``
+
+A boolean that turns on/off debug mode.
+
+If you define custom settings, `django/views/debug.py`_ has a ``HIDDEN_SETTINGS``
+regular expression which will hide from the DEBUG view anything that contains
+``'SECRET'``, ``'PASSWORD'``, ``'PROFANITIES'``, or ``'SIGNATURE'``. This allows
+untrusted users to be able to give backtraces without seeing sensitive (or
+offensive) settings.
+
+Still, note that there are always going to be sections of your debug output that
+are inappropriate for public consumption. File paths, configuration options, and
+the like all give attackers extra information about your server.
+
+It is also important to remember that when running with ``DEBUG`` turned on, Django
+will remember every SQL query it executes. This is useful when you are debugging,
+but on a production server, it will rapidly consume memory.
+
+Never deploy a site into production with ``DEBUG`` turned on.
+
+.. _django/views/debug.py: http://code.djangoproject.com/browser/django/trunk/django/views/debug.py
+
+DEBUG_PROPAGATE_EXCEPTIONS
+--------------------------
+
+.. versionadded:: 1.0
+
+Default: ``False``
+
+If set to True, Django's normal exception handling of view functions
+will be suppressed, and exceptions will propagate upwards.  This can
+be useful for some test setups, and should never be used on a live
+site.
+
+.. setting:: DECIMAL_SEPARATOR
+
+DECIMAL_SEPARATOR
+-----------------
+
+.. versionadded:: 1.2
+
+Default: ``'.'`` (Dot)
+
+Default decimal separator used when formatting decimal numbers.
+
+.. setting:: DEFAULT_CHARSET
+
+DEFAULT_CHARSET
+---------------
+
+Default: ``'utf-8'``
+
+Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't
+manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the
+``Content-Type`` header.
+
+.. setting:: DEFAULT_CONTENT_TYPE
+
+DEFAULT_CONTENT_TYPE
+--------------------
+
+Default: ``'text/html'``
+
+Default content type to use for all ``HttpResponse`` objects, if a MIME type
+isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
+``Content-Type`` header.
+
+.. setting:: DEFAULT_FILE_STORAGE
+
+DEFAULT_FILE_STORAGE
+--------------------
+
+Default: :class:`django.core.files.storage.FileSystemStorage`
+
+Default file storage class to be used for any file-related operations that don't
+specify a particular storage system. See :doc:`/topics/files`.
+
+.. setting:: DEFAULT_FROM_EMAIL
+
+DEFAULT_FROM_EMAIL
+------------------
+
+Default: ``'webmaster@localhost'``
+
+Default e-mail address to use for various automated correspondence from the
+site manager(s).
+
+.. setting:: DEFAULT_INDEX_TABLESPACE
+
+DEFAULT_INDEX_TABLESPACE
+------------------------
+
+.. versionadded:: 1.0
+
+Default: ``''`` (Empty string)
+
+Default tablespace to use for indexes on fields that don't specify
+one, if the backend supports it.
+
+.. setting:: DEFAULT_TABLESPACE
+
+DEFAULT_TABLESPACE
+------------------
+
+.. versionadded:: 1.0
+
+Default: ``''`` (Empty string)
+
+Default tablespace to use for models that don't specify one, if the
+backend supports it.
+
+.. setting:: DISALLOWED_USER_AGENTS
+
+DISALLOWED_USER_AGENTS
+----------------------
+
+Default: ``()`` (Empty tuple)
+
+List of compiled regular expression objects representing User-Agent strings that
+are not allowed to visit any page, systemwide. Use this for bad robots/crawlers.
+This is only used if ``CommonMiddleware`` is installed (see
+:doc:`/topics/http/middleware`).
+
+.. setting:: EMAIL_BACKEND
+
+EMAIL_BACKEND
+-------------
+
+.. versionadded:: 1.2
+
+Default: ``'django.core.mail.backends.smtp.EmailBackend'``
+
+The backend to use for sending emails. For the list of available backends see
+:doc:`/topics/email`.
+
+.. setting:: EMAIL_FILE_PATH
+
+EMAIL_FILE_PATH
+---------------
+
+.. versionadded:: 1.2
+
+Default: Not defined
+
+The directory used by the ``file`` email backend to store output files.
+
+.. setting:: EMAIL_HOST
+
+EMAIL_HOST
+----------
+
+Default: ``'localhost'``
+
+The host to use for sending e-mail.
+
+See also ``EMAIL_PORT``.
+
+.. setting:: EMAIL_HOST_PASSWORD
+
+EMAIL_HOST_PASSWORD
+-------------------
+
+Default: ``''`` (Empty string)
+
+Password to use for the SMTP server defined in ``EMAIL_HOST``. This setting is
+used in conjunction with ``EMAIL_HOST_USER`` when authenticating to the SMTP
+server. If either of these settings is empty, Django won't attempt
+authentication.
+
+See also ``EMAIL_HOST_USER``.
+
+.. setting:: EMAIL_HOST_USER
+
+EMAIL_HOST_USER
+---------------
+
+Default: ``''`` (Empty string)
+
+Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty,
+Django won't attempt authentication.
+
+See also ``EMAIL_HOST_PASSWORD``.
+
+.. setting:: EMAIL_PORT
+
+EMAIL_PORT
+----------
+
+Default: ``25``
+
+Port to use for the SMTP server defined in ``EMAIL_HOST``.
+
+.. setting:: EMAIL_SUBJECT_PREFIX
+
+EMAIL_SUBJECT_PREFIX
+--------------------
+
+Default: ``'[Django] '``
+
+Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins``
+or ``django.core.mail.mail_managers``. You'll probably want to include the
+trailing space.
+
+.. setting:: EMAIL_USE_TLS
+
+EMAIL_USE_TLS
+-------------
+
+.. versionadded:: 1.0
+
+Default: ``False``
+
+Whether to use a TLS (secure) connection when talking to the SMTP server.
+
+.. setting:: FILE_CHARSET
+
+FILE_CHARSET
+------------
+
+.. versionadded:: 1.0
+
+Default: ``'utf-8'``
+
+The character encoding used to decode any files read from disk. This includes
+template files and initial SQL data files.
+
+.. setting:: FILE_UPLOAD_HANDLERS
+
+FILE_UPLOAD_HANDLERS
+--------------------
+
+.. versionadded:: 1.0
+
+Default::
+
+    ("django.core.files.uploadhandler.MemoryFileUploadHandler",
+     "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
+
+A tuple of handlers to use for uploading. See :doc:`/topics/files` for details.
+
+.. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE
+
+FILE_UPLOAD_MAX_MEMORY_SIZE
+---------------------------
+
+.. versionadded:: 1.0
+
+Default: ``2621440`` (i.e. 2.5 MB).
+
+The maximum size (in bytes) that an upload will be before it gets streamed to
+the file system. See :doc:`/topics/files` for details.
+
+.. setting:: FILE_UPLOAD_PERMISSIONS
+
+FILE_UPLOAD_PERMISSIONS
+-----------------------
+
+Default: ``None``
+
+The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
+more information about what these modes mean, see the `documentation for
+os.chmod`_
+
+If this isn't given or is ``None``, you'll get operating-system
+dependent behavior. On most platforms, temporary files will have a mode
+of ``0600``, and files saved from memory will be saved using the
+system's standard umask.
+
+.. warning::
+
+    **Always prefix the mode with a 0.**
+
+    If you're not familiar with file modes, please note that the leading
+    ``0`` is very important: it indicates an octal number, which is the
+    way that modes must be specified. If you try to use ``644``, you'll
+    get totally incorrect behavior.
+
+
+.. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod
+
+.. setting:: FILE_UPLOAD_TEMP_DIR
+
+FILE_UPLOAD_TEMP_DIR
+--------------------
+
+.. versionadded:: 1.0
+
+Default: ``None``
+
+The directory to store data temporarily while uploading files. If ``None``,
+Django will use the standard temporary directory for the operating system. For
+example, this will default to '/tmp' on \*nix-style operating systems.
+
+See :doc:`/topics/files` for details.
+
+.. setting:: FIRST_DAY_OF_WEEK
+
+FIRST_DAY_OF_WEEK
+-----------------
+
+.. versionadded:: 1.2
+
+Default: ``0`` (Sunday)
+
+Number representing the first day of the week. This is especially useful
+when displaying a calendar. This value is only used when not using
+format internationalization, or when a format cannot be found for the
+current locale.
+
+The value must be an integer from 0 to 6, where 0 means Sunday, 1 means
+Monday and so on.
+
+.. setting:: FIXTURE_DIRS
+
+FIXTURE_DIRS
+-------------
+
+Default: ``()`` (Empty tuple)
+
+List of locations of the fixture data files, in search order. Note that
+these paths should use Unix-style forward slashes, even on Windows. See
+:doc:`/topics/testing`.
+
+FORCE_SCRIPT_NAME
+------------------
+
+Default: ``None``
+
+If not ``None``, this will be used as the value of the ``SCRIPT_NAME``
+environment variable in any HTTP request. This setting can be used to override
+the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
+of the preferred value or not supplied at all.
+
+.. setting:: FORMAT_MODULE_PATH
+
+FORMAT_MODULE_PATH
+------------------
+
+.. versionadded:: 1.2
+
+Default: ``None``
+
+A full Python path to a Python package that contains format definitions for
+project locales. If not ``None``, Django will check for a ``formats.py``
+file, under the directory named as the current locale, and will use the
+formats defined on this file.
+
+For example, if ``FORMAT_MODULE_PATH`` is set to ``mysite.formats``, and
+current language is ``en`` (English), Django will expect a directory tree
+like::
+
+    mysite/
+        formats/
+            __init__.py
+            en/
+                __init__.py
+                formats.py
+
+Available formats are ``DATE_FORMAT``, ``TIME_FORMAT``, ``DATETIME_FORMAT``,
+``YEAR_MONTH_FORMAT``, ``MONTH_DAY_FORMAT``, ``SHORT_DATE_FORMAT``,
+``SHORT_DATETIME_FORMAT``, ``FIRST_DAY_OF_WEEK``, ``DECIMAL_SEPARATOR``,
+``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``.
+
+.. setting:: IGNORABLE_404_ENDS
+
+IGNORABLE_404_ENDS
+------------------
+
+Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
+
+See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
+
+.. setting:: IGNORABLE_404_STARTS
+
+IGNORABLE_404_STARTS
+--------------------
+
+Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
+
+A tuple of strings that specify beginnings of URLs that should be ignored by
+the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
+the :doc:`/howto/error-reporting`.
+
+.. setting:: INSTALLED_APPS
+
+INSTALLED_APPS
+--------------
+
+Default: ``()`` (Empty tuple)
+
+A tuple of strings designating all applications that are enabled in this Django
+installation. Each string should be a full Python path to a Python package that
+contains a Django application, as created by :djadmin:`django-admin.py startapp
+<startapp>`.
+
+.. admonition:: App names must be unique
+
+    The application names (that is, the final dotted part of the
+    path to the module containing ``models.py``) defined in
+    :setting:`INSTALLED_APPS` *must* be unique. For example, you can't
+    include both ``django.contrib.auth`` and ``myproject.auth`` in
+    INSTALLED_APPS.
+
+.. setting:: INTERNAL_IPS
+
+INTERNAL_IPS
+------------
+
+Default: ``()`` (Empty tuple)
+
+A tuple of IP addresses, as strings, that:
+
+    * See debug comments, when ``DEBUG`` is ``True``
+    * Receive X headers if the ``XViewMiddleware`` is installed (see
+      :doc:`/topics/http/middleware`)
+
+.. setting:: LANGUAGE_CODE
+
+LANGUAGE_CODE
+-------------
+
+Default: ``'en-us'``
+
+A string representing the language code for this installation. This should be in
+standard :term:`language format<language code>`. For example, U.S. English is
+``"en-us"``. See :doc:`/topics/i18n/index`.
+
+.. setting:: LANGUAGE_COOKIE_NAME
+
+LANGUAGE_COOKIE_NAME
+--------------------
+
+.. versionadded:: 1.0
+
+Default: ``'django_language'``
+
+The name of the cookie to use for the language cookie. This can be whatever you
+want (but should be different from ``SESSION_COOKIE_NAME``). See
+:doc:`/topics/i18n/index`.
+
+.. setting:: LANGUAGES
+
+LANGUAGES
+---------
+
+Default: A tuple of all available languages. This list is continually growing
+and including a copy here would inevitably become rapidly out of date. You can
+see the current list of translated languages by looking in
+``django/conf/global_settings.py`` (or view the `online source`_).
+
+.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
+
+The list is a tuple of two-tuples in the format ``(language code, language
+name)``, the ``language code`` part should be a
+:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``.
+This specifies which languages are available for language selection. See
+:doc:`/topics/i18n/index`.
+
+Generally, the default value should suffice. Only set this setting if you want
+to restrict language selection to a subset of the Django-provided languages.
+
+If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as
+translation strings (as in the default value referred to above) -- but use a
+"dummy" ``gettext()`` function, not the one in ``django.utils.translation``.
+You should *never* import ``django.utils.translation`` from within your
+settings file, because that module in itself depends on the settings, and that
+would cause a circular import.
+
+The solution is to use a "dummy" ``gettext()`` function. Here's a sample
+settings file::
+
+    gettext = lambda s: s
+
+    LANGUAGES = (
+        ('de', gettext('German')),
+        ('en', gettext('English')),
+    )
+
+With this arrangement, ``django-admin.py makemessages`` will still find and
+mark these strings for translation, but the translation won't happen at
+runtime -- so you'll have to remember to wrap the languages in the *real*
+``gettext()`` in any code that uses ``LANGUAGES`` at runtime.
+
+.. setting:: LOCALE_PATHS
+
+LOCALE_PATHS
+------------
+
+Default: ``()`` (Empty tuple)
+
+A tuple of directories where Django looks for translation files.
+See :ref:`using-translations-in-your-own-projects`.
+
+.. setting:: LOGIN_REDIRECT_URL
+
+LOGIN_REDIRECT_URL
+------------------
+
+.. versionadded:: 1.0
+
+Default: ``'/accounts/profile/'``
+
+The URL where requests are redirected after login when the
+``contrib.auth.login`` view gets no ``next`` parameter.
+
+This is used by the :func:`~django.contrib.auth.decorators.login_required`
+decorator, for example.
+
+.. setting:: LOGIN_URL
+
+LOGIN_URL
+---------
+
+.. versionadded:: 1.0
+
+Default: ``'/accounts/login/'``
+
+The URL where requests are redirected for login, especially when using the
+:func:`~django.contrib.auth.decorators.login_required` decorator.
+
+.. setting:: LOGOUT_URL
+
+LOGOUT_URL
+----------
+
+.. versionadded:: 1.0
+
+Default: ``'/accounts/logout/'``
+
+LOGIN_URL counterpart.
+
+.. setting:: MANAGERS
+
+MANAGERS
+--------
+
+Default: ``()`` (Empty tuple)
+
+A tuple in the same format as ``ADMINS`` that specifies who should get
+broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
+
+.. setting:: MEDIA_ROOT
+
+MEDIA_ROOT
+----------
+
+Default: ``''`` (Empty string)
+
+Absolute path to the directory that holds media for this installation.
+Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``.
+
+.. setting:: MEDIA_URL
+
+MEDIA_URL
+---------
+
+Default: ``''`` (Empty string)
+
+URL that handles the media served from ``MEDIA_ROOT``.
+Example: ``"http://media.lawrence.com"``
+
+Note that this should have a trailing slash if it has a path component.
+
+Good: ``"http://www.example.com/static/"``
+Bad: ``"http://www.example.com/static"``
+
+.. setting:: MIDDLEWARE_CLASSES
+
+MESSAGE_LEVEL
+-------------
+
+.. versionadded:: 1.2
+
+Default: `messages.INFO`
+
+Sets the minimum message level that will be recorded by the messages
+framework. See the :doc:`messages documentation </ref/contrib/messages>` for
+more details.
+
+MESSAGE_STORAGE
+---------------
+
+.. versionadded:: 1.2
+
+Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
+
+Controls where Django stores message data.  See the
+:doc:`messages documentation </ref/contrib/messages>` for more details.
+
+MESSAGE_TAGS
+------------
+
+.. versionadded:: 1.2
+
+Default::
+
+        {messages.DEBUG: 'debug',
+        messages.INFO: 'info',
+        messages.SUCCESS: 'success',
+        messages.WARNING: 'warning',
+        messages.ERROR: 'error',}
+
+Sets the mapping of message levels to message tags. See the
+:doc:`messages documentation </ref/contrib/messages>` for more details.
+
+MIDDLEWARE_CLASSES
+------------------
+
+Default::
+
+    ('django.middleware.common.CommonMiddleware',
+     'django.contrib.sessions.middleware.SessionMiddleware',
+     'django.middleware.csrf.CsrfViewMiddleware',
+     'django.contrib.auth.middleware.AuthenticationMiddleware',
+     'django.contrib.messages.middleware.MessageMiddleware',)
+
+A tuple of middleware classes to use. See :doc:`/topics/http/middleware`.
+
+.. versionchanged:: 1.2
+   ``'django.contrib.messages.middleware.MessageMiddleware'`` was added to the
+   default.  For more information, see the :doc:`messages documentation
+   </ref/contrib/messages>`.
+
+.. setting:: MONTH_DAY_FORMAT
+
+MONTH_DAY_FORMAT
+----------------
+
+Default: ``'F j'``
+
+The default formatting to use for date fields on Django admin change-list
+pages -- and, possibly, by other parts of the system -- in cases when only the
+month and day are displayed.
+
+For example, when a Django admin change-list page is being filtered by a date
+drilldown, the header for a given day displays the day and month. Different
+locales have different formats. For example, U.S. English would say
+"January 1," whereas Spanish might say "1 Enero."
+
+See :tfilter:`allowed date format strings <date>`. See also ``DATE_FORMAT``,
+``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``YEAR_MONTH_FORMAT``.
+
+.. setting:: NUMBER_GROUPING
+
+NUMBER_GROUPING
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``0``
+
+Number of digits grouped together on the integer part of a number. Common use
+is to display a thousand separator. If this setting is ``0``, then, no grouping
+will be applied to the number. If this setting is greater than ``0`` then the
+setting :setting:`THOUSAND_SEPARATOR` will be used as the separator between those
+groups.
+
+See also :setting:`THOUSAND_SEPARATOR` and :setting:`USE_THOUSAND_SEPARATOR`.
+
+.. setting:: PASSWORD_RESET_TIMEOUT_DAYS
+
+PASSWORD_RESET_TIMEOUT_DAYS
+---------------------------
+
+Default: ``3``
+
+The number of days a password reset link is valid for. Used by the
+:mod:`django.contrib.auth` password reset mechanism.
+
+.. setting:: PREPEND_WWW
+
+PREPEND_WWW
+-----------
+
+Default: ``False``
+
+Whether to prepend the "www." subdomain to URLs that don't have it. This is only
+used if :class:`~django.middleware.common.CommonMiddleware` is installed
+(see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`.
+
+.. setting:: PROFANITIES_LIST
+
+PROFANITIES_LIST
+----------------
+
+A tuple of profanities, as strings, that will trigger a validation error when
+the ``hasNoProfanities`` validator is called.
+
+We don't list the default values here, because that would be profane. To see
+the default values, see the file `django/conf/global_settings.py`_.
+
+.. _django/conf/global_settings.py: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
+
+.. setting:: RESTRUCTUREDTEXT_FILTER_SETTINGS
+
+RESTRUCTUREDTEXT_FILTER_SETTINGS
+--------------------------------
+
+Default: ``{}``
+
+A dictionary containing settings for the ``restructuredtext`` markup filter from
+the :doc:`django.contrib.markup application </ref/contrib/markup>`. They override
+the default writer settings. See the Docutils restructuredtext `writer settings
+docs`_ for details.
+
+.. _writer settings docs: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer
+
+.. setting:: ROOT_URLCONF
+
+ROOT_URLCONF
+------------
+
+Default: Not defined
+
+A string representing the full Python import path to your root URLconf. For example:
+``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
+setting the attribute ``urlconf`` on the incoming ``HttpRequest``
+object. See :ref:`how-django-processes-a-request` for details.
+
+.. setting:: SECRET_KEY
+
+SECRET_KEY
+----------
+
+Default: ``''`` (Empty string)
+
+A secret key for this particular Django installation. Used to provide a seed in
+secret-key hashing algorithms. Set this to a random string -- the longer, the
+better. ``django-admin.py startproject`` creates one automatically.
+
+.. setting:: SEND_BROKEN_LINK_EMAILS
+
+SEND_BROKEN_LINK_EMAILS
+-----------------------
+
+Default: ``False``
+
+Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
+Django-powered page that is 404ed with a non-empty referer (i.e., a broken
+link). This is only used if ``CommonMiddleware`` is installed (see
+:doc:`/topics/http/middleware`. See also ``IGNORABLE_404_STARTS``,
+``IGNORABLE_404_ENDS`` and :doc:`/howto/error-reporting`.
+
+.. setting:: SERIALIZATION_MODULES
+
+SERIALIZATION_MODULES
+---------------------
+
+Default: Not defined.
+
+A dictionary of modules containing serializer definitions (provided as
+strings), keyed by a string identifier for that serialization type. For
+example, to define a YAML serializer, use::
+
+    SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' }
+
+.. setting:: SERVER_EMAIL
+
+SERVER_EMAIL
+------------
+
+Default: ``'root@localhost'``
+
+The e-mail address that error messages come from, such as those sent to
+``ADMINS`` and ``MANAGERS``.
+
+.. setting:: SESSION_COOKIE_AGE
+
+SESSION_COOKIE_AGE
+------------------
+
+Default: ``1209600`` (2 weeks, in seconds)
+
+The age of session cookies, in seconds. See :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_COOKIE_DOMAIN
+
+SESSION_COOKIE_DOMAIN
+---------------------
+
+Default: ``None``
+
+The domain to use for session cookies. Set this to a string such as
+``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
+domain cookie. See the :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_COOKIE_NAME
+
+SESSION_COOKIE_NAME
+-------------------
+
+Default: ``'sessionid'``
+
+The name of the cookie to use for sessions. This can be whatever you want (but
+should be different from ``LANGUAGE_COOKIE_NAME``). See the :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_COOKIE_PATH
+
+SESSION_COOKIE_PATH
+-------------------
+
+.. versionadded:: 1.0
+
+Default: ``'/'``
+
+The path set on the session cookie. This should either match the URL path of your
+Django installation or be parent of that path.
+
+This is useful if you have multiple Django instances running under the same
+hostname. They can use different cookie paths, and each instance will only see
+its own session cookie.
+
+.. setting:: SESSION_COOKIE_SECURE
+
+SESSION_COOKIE_SECURE
+---------------------
+
+Default: ``False``
+
+Whether to use a secure cookie for the session cookie. If this is set to
+``True``, the cookie will be marked as "secure," which means browsers may
+ensure that the cookie is only sent under an HTTPS connection.
+See the :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_ENGINE
+
+SESSION_ENGINE
+--------------
+
+.. versionadded:: 1.0
+
+.. versionchanged:: 1.1
+   The ``cached_db`` backend was added
+
+Default: ``django.contrib.sessions.backends.db``
+
+Controls where Django stores session data. Valid values are:
+
+    * ``'django.contrib.sessions.backends.db'``
+    * ``'django.contrib.sessions.backends.file'``
+    * ``'django.contrib.sessions.backends.cache'``
+    * ``'django.contrib.sessions.backends.cached_db'``
+
+See :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
+
+SESSION_EXPIRE_AT_BROWSER_CLOSE
+-------------------------------
+
+Default: ``False``
+
+Whether to expire the session when the user closes his or her browser.
+See the :doc:`/topics/http/sessions`.
+
+.. setting:: SESSION_FILE_PATH
+
+SESSION_FILE_PATH
+-----------------
+
+.. versionadded:: 1.0
+
+Default: ``None``
+
+If you're using file-based session storage, this sets the directory in
+which Django will store session data. See :doc:`/topics/http/sessions`. When
+the default value (``None``) is used, Django will use the standard temporary
+directory for the system.
+
+.. setting:: SESSION_SAVE_EVERY_REQUEST
+
+SESSION_SAVE_EVERY_REQUEST
+--------------------------
+
+Default: ``False``
+
+Whether to save the session data on every request. See
+:doc:`/topics/http/sessions`.
+
+.. setting:: SHORT_DATE_FORMAT
+
+SHORT_DATE_FORMAT
+-----------------
+
+.. versionadded:: 1.2
+
+Default: ``m/d/Y`` (e.g. ``12/31/2003``)
+
+An available formatting that can be used for displaying date fields on
+templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
+corresponding locale-dictated format has higher precedence and will be applied.
+See :tfilter:`allowed date format strings <date>`.
+
+See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
+
+.. setting:: SHORT_DATETIME_FORMAT
+
+SHORT_DATETIME_FORMAT
+---------------------
+
+.. versionadded:: 1.2
+
+Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``)
+
+An available formatting that can be used for displaying datetime fields on
+templates. Note that if :setting:`USE_L10N` is set to ``True``, then the
+corresponding locale-dictated format has higher precedence and will be applied.
+See :tfilter:`allowed date format strings <date>`.
+
+See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``.
+
+.. setting:: SITE_ID
+
+SITE_ID
+-------
+
+Default: Not defined
+
+The ID, as an integer, of the current site in the ``django_site`` database
+table. This is used so that application data can hook into specific site(s)
+and a single database can manage content for multiple sites.
+
+See :doc:`/ref/contrib/sites`.
+
+.. _site framework docs: ../sites/
+
+.. setting:: TEMPLATE_CONTEXT_PROCESSORS
+
+TEMPLATE_CONTEXT_PROCESSORS
+---------------------------
+
+Default::
+
+    ("django.contrib.auth.context_processors.auth",
+    "django.core.context_processors.debug",
+    "django.core.context_processors.i18n",
+    "django.core.context_processors.media",
+    "django.contrib.messages.context_processors.messages")
+
+A tuple of callables that are used to populate the context in ``RequestContext``.
+These callables take a request object as their argument and return a dictionary
+of items to be merged into the context.
+
+.. versionchanged:: 1.2
+   ``"django.contrib.messages.context_processors.messages"`` was added to the
+   default.  For more information, see the :doc:`messages documentation
+   </ref/contrib/messages>`.
+
+.. versionchanged:: 1.2
+    The auth context processor was moved in this release from its old location
+    ``django.core.context_processors.auth`` to
+    ``django.contrib.auth.context_processors.auth``.
+
+.. setting:: TEMPLATE_DEBUG
+
+TEMPLATE_DEBUG
+--------------
+
+Default: ``False``
+
+A boolean that turns on/off template debug mode. If this is ``True``, the fancy
+error page will display a detailed report for any ``TemplateSyntaxError``. This
+report contains the relevant snippet of the template, with the appropriate line
+highlighted.
+
+Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so
+you'll want to set that to take advantage of this setting.
+
+See also ``DEBUG``.
+
+.. setting:: TEMPLATE_DIRS
+
+TEMPLATE_DIRS
+-------------
+
+Default: ``()`` (Empty tuple)
+
+List of locations of the template source files, in search order. Note that
+these paths should use Unix-style forward slashes, even on Windows.
+
+See :doc:`/topics/templates`.
+
+.. setting:: TEMPLATE_LOADERS
+
+TEMPLATE_LOADERS
+----------------
+
+Default::
+
+     ('django.template.loaders.filesystem.Loader',
+      'django.template.loaders.app_directories.Loader')
+
+A tuple of template loader classes, specified as strings. Each ``Loader`` class
+knows how to import templates from a particular source. Optionally, a tuple can be
+used instead of a string. The first item in the tuple should be the ``Loader``'s
+module, subsequent items are passed to the ``Loader`` during initialization. See
+:doc:`/ref/templates/api`.
+
+.. setting:: TEMPLATE_STRING_IF_INVALID
+
+TEMPLATE_STRING_IF_INVALID
+--------------------------
+
+Default: ``''`` (Empty string)
+
+Output, as a string, that the template system should use for invalid (e.g.
+misspelled) variables. See :ref:`invalid-template-variables`..
+
+.. setting:: TEST_RUNNER
+
+TEST_RUNNER
+-----------
+
+Default: ``'django.test.simple.DjangoTestSuiteRunner'``
+
+.. versionchanged:: 1.2
+   Prior to 1.2, test runners were a function, not a class.
+
+The name of the class to use for starting the test suite. See
+:doc:`/topics/testing`.
+
+.. _Testing Django Applications: ../testing/
+
+.. setting:: THOUSAND_SEPARATOR
+
+THOUSAND_SEPARATOR
+------------------
+
+.. versionadded:: 1.2
+
+Default ``,`` (Comma)
+
+Default thousand separator used when formatting numbers. This setting is
+used only when ``NUMBER_GROUPING`` and ``USE_THOUSAND_SEPARATOR`` are set.
+
+See also :setting:`NUMBER_GROUPING`, :setting:`DECIMAL_SEPARATOR` and
+:setting:`USE_THOUSAND_SEPARATOR`.
+
+.. setting:: TIME_FORMAT
+
+TIME_FORMAT
+-----------
+
+Default: ``'P'`` (e.g. ``4 p.m.``)
+
+The default formatting to use for displaying time fields in any part of the
+system. Note that if :setting:`USE_L10N` is set to ``True``, then the
+locale-dictated format has higher precedence and will be applied instead. See
+:tfilter:`allowed date format strings <date>`.
+
+.. versionchanged:: 1.2
+    This setting can now be overriden by setting ``USE_L10N`` to ``True``.
+
+See also ``DATE_FORMAT`` and ``DATETIME_FORMAT``.
+
+.. setting:: TIME_INPUT_FORMATS
+
+TIME_INPUT_FORMATS
+------------------
+
+.. versionadded:: 1.2
+
+Default: ``('%H:%M:%S', '%H:%M')``
+
+A tuple of formats that will be accepted when inputting data on a time
+field. Formats will be tried in order, using the first valid.
+Note that these format strings are specified in Python's datetime_ module
+syntax, that is different from the one used by Django for formatting dates
+to be displayed.
+
+See also ``DATE_INPUT_FORMATS`` and ``DATETIME_INPUT_FORMATS``.
+
+.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+
+.. setting:: TIME_ZONE
+
+TIME_ZONE
+---------
+
+Default: ``'America/Chicago'``
+
+.. versionchanged:: 1.2
+   ``None`` was added as an allowed value.
+
+A string representing the time zone for this installation, or
+``None``. `See available choices`_. (Note that list of available
+choices lists more than one on the same line; you'll want to use just
+one of the choices for a given time zone. For instance, one line says
+``'Europe/London GB GB-Eire'``, but you should use the first bit of
+that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.)
+
+Note that this is the time zone to which Django will convert all
+dates/times -- not necessarily the timezone of the server. For
+example, one server may serve multiple Django-powered sites, each with
+a separate time-zone setting.
+
+Normally, Django sets the ``os.environ['TZ']`` variable to the time
+zone you specify in the ``TIME_ZONE`` setting. Thus, all your views
+and models will automatically operate in the correct time zone.
+However, Django won't set the ``TZ`` environment variable under the
+following conditions:
+
+ * If you're using the manual configuration option as described in
+   :ref:`manually configuring settings
+   <settings-without-django-settings-module>`, or
+
+ * If you specify ``TIME_ZONE = None``. This will cause Django to fall
+   back to using the system timezone.
+
+If Django doesn't set the ``TZ`` environment variable, it's up to you
+to ensure your processes are running in the correct environment.
+
+.. note::
+    Django cannot reliably use alternate time zones in a Windows
+    environment. If you're running Django on Windows, this variable
+    must be set to match the system timezone.
+
+
+.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
+
+.. setting:: URL_VALIDATOR_USER_AGENT
+
+URL_VALIDATOR_USER_AGENT
+------------------------
+
+Default: ``Django/<version> (http://www.djangoproject.com/)``
+
+The string to use as the ``User-Agent`` header when checking to see if URLs
+exist (see the ``verify_exists`` option on :class:`~django.db.models.URLField`).
+
+.. setting:: USE_ETAGS
+
+USE_ETAGS
+---------
+
+Default: ``False``
+
+A boolean that specifies whether to output the "Etag" header. This saves
+bandwidth but slows down performance. This is only used if ``CommonMiddleware``
+is installed (see :doc:`/topics/http/middleware`).
+
+.. setting:: USE_I18N
+
+USE_I18N
+--------
+
+Default: ``True``
+
+A boolean that specifies whether Django's internationalization system should be
+enabled. This provides an easy way to turn it off, for performance. If this is
+set to ``False``, Django will make some optimizations so as not to load the
+internationalization machinery.
+
+See also ``USE_L10N``
+
+.. setting:: USE_L10N
+
+USE_L10N
+--------
+
+.. versionadded:: 1.2
+
+Default ``False``
+
+A boolean that specifies if data will be localized by default or not. If this
+is set to ``True``, e.g. Django will display numbers and dates using the
+format of the current locale.
+
+See also ``USE_I18N`` and ``LANGUAGE_CODE``
+
+.. setting:: USE_THOUSAND_SEPARATOR
+
+USE_THOUSAND_SEPARATOR
+----------------------
+
+.. versionadded:: 1.2
+
+Default ``False``
+
+A boolean that specifies wheter to display numbers using a thousand separator.
+If this is set to ``True``, Django will use values from ``THOUSAND_SEPARATOR``
+and ``NUMBER_GROUPING`` from current locale, to format the number.
+``USE_L10N`` must be set to ``True``, in order to format numbers.
+
+See also ``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``.
+
+.. setting:: YEAR_MONTH_FORMAT
+
+YEAR_MONTH_FORMAT
+-----------------
+
+Default: ``'F Y'``
+
+The default formatting to use for date fields on Django admin change-list
+pages -- and, possibly, by other parts of the system -- in cases when only the
+year and month are displayed.
+
+For example, when a Django admin change-list page is being filtered by a date
+drilldown, the header for a given month displays the month and the year.
+Different locales have different formats. For example, U.S. English would say
+"January 2006," whereas another locale might say "2006/January."
+
+See :tfilter:`allowed date format strings <date>`. See also ``DATE_FORMAT``,
+``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``.
+
+Deprecated settings
+===================
+
+.. setting:: DATABASE_ENGINE
+
+DATABASE_ENGINE
+---------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`ENGINE` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_HOST
+
+DATABASE_HOST
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`HOST` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_NAME
+
+DATABASE_NAME
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`NAME` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_OPTIONS
+
+DATABASE_OPTIONS
+----------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`OPTIONS` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_PASSWORD
+
+DATABASE_PASSWORD
+-----------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`PASSWORD` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_PORT
+
+DATABASE_PORT
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`PORT` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_USER
+
+DATABASE_USER
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`USER` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_CHARSET
+
+TEST_DATABASE_CHARSET
+---------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_CHARSET` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_COLLATION
+
+TEST_DATABASE_COLLATION
+-----------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_COLLATION` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_NAME
+
+TEST_DATABASE_NAME
+------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_NAME` in
+   :setting:`DATABASES`.
+
diff --git a/parts/django/docs/ref/signals.txt b/parts/django/docs/ref/signals.txt
new file mode 100644
index 0000000..4bc1f3f
--- /dev/null
+++ b/parts/django/docs/ref/signals.txt
@@ -0,0 +1,475 @@
+=======
+Signals
+=======
+
+A list of all the signals that Django sends.
+
+.. seealso::
+
+    See the documentation on the :doc:`signal dispatcher </topics/signals>` for
+    information regarding how to register for and receive signals.
+
+    The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set
+    of comment-related signals </ref/contrib/comments/signals>`.
+
+Model signals
+=============
+
+.. module:: django.db.models.signals
+   :synopsis: Signals sent by the model system.
+
+The :mod:`django.db.models.signals` module defines a set of signals sent by the
+module system.
+
+.. warning::
+
+    Many of these signals are sent by various model methods like
+    :meth:`~django.db.models.Model.__init__` or
+    :meth:`~django.db.models.Model.save` that you can overwrite in your own
+    code.
+
+    If you override these methods on your model, you must call the parent class'
+    methods for this signals to be sent.
+
+	Note also that Django stores signal handlers as weak references by default,
+	so if your handler is a local function, it may be garbage collected.  To
+	prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`.
+
+pre_init
+--------
+
+.. attribute:: django.db.models.signals.pre_init
+   :module:
+
+.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module.
+
+Whenever you instantiate a Django model,, this signal is sent at the beginning
+of the model's :meth:`~django.db.models.Model.__init__` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class that just had an instance created.
+
+    ``args``
+        A list of positional arguments passed to
+        :meth:`~django.db.models.Model.__init__`:
+
+    ``kwargs``
+        A dictionary of keyword arguments passed to
+        :meth:`~django.db.models.Model.__init__`:.
+
+For example, the :doc:`tutorial </intro/tutorial01>` has this line:
+
+.. code-block:: python
+
+    p = Poll(question="What's up?", pub_date=datetime.now())
+
+The arguments sent to a :data:`pre_init` handler would be:
+
+    ==========  ===============================================================
+    Argument    Value
+    ==========  ===============================================================
+    ``sender``  ``Poll`` (the class itself)
+
+    ``args``    ``[]`` (an empty list because there were no positional
+                arguments passed to ``__init__``.)
+
+    ``kwargs``  ``{'question': "What's up?", 'pub_date': datetime.now()}``
+    ==========  ===============================================================
+
+post_init
+---------
+
+.. data:: django.db.models.signals.post_init
+   :module:
+
+Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes.
+
+Arguments sent with this signal:
+
+    ``sender``
+        As above: the model class that just had an instance created.
+
+    ``instance``
+        The actual instance of the model that's just been created.
+
+pre_save
+--------
+
+.. data:: django.db.models.signals.pre_save
+   :module:
+
+This is sent at the beginning of a model's :meth:`~django.db.models.Model.save`
+method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+post_save
+---------
+
+.. data:: django.db.models.signals.post_save
+   :module:
+
+Like :data:`pre_save`, but sent at the end of the
+:meth:`~django.db.models.Model.save` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being saved.
+
+    ``created``
+        A boolean; ``True`` if a new record was created.
+
+pre_delete
+----------
+
+.. data:: django.db.models.signals.pre_delete
+   :module:
+
+Sent at the beginning of a model's :meth:`~django.db.models.Model.delete`
+method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being deleted.
+
+post_delete
+-----------
+
+.. data:: django.db.models.signals.post_delete
+   :module:
+
+Like :data:`pre_delete`, but sent at the end of the
+:meth:`~django.db.models.Model.delete` method.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The model class.
+
+    ``instance``
+        The actual instance being deleted.
+
+        Note that the object will no longer be in the database, so be very
+        careful what you do with this instance.
+
+m2m_changed
+-----------
+
+.. data:: django.db.models.signals.m2m_changed
+   :module:
+
+.. versionadded:: 1.2
+
+Sent when a :class:`ManyToManyField` is changed on a model instance.
+Strictly speaking, this is not a model signal since it is sent by the
+:class:`ManyToManyField`, but since it complements the
+:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete`
+when it comes to tracking changes to models, it is included here.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The intermediate model class describing the :class:`ManyToManyField`.
+        This class is automatically created when a many-to-many field is
+        defined; you can access it using the ``through`` attribute on the
+        many-to-many field.
+
+    ``instance``
+        The instance whose many-to-many relation is updated. This can be an
+        instance of the ``sender``, or of the class the :class:`ManyToManyField`
+        is related to.
+
+    ``action``
+        A string indicating the type of update that is done on the relation.
+        This can be one of the following:
+
+        ``"pre_add"``
+            Sent *before* one or more objects are added to the relation
+        ``"post_add"``
+            Sent *after* one or more objects are added to the relation
+        ``"pre_remove"``
+            Sent *after* one or more objects are removed from the relation
+        ``"post_remove"``
+            Sent *after* one or more objects are removed from the relation
+        ``"pre_clear"``
+            Sent *before* the relation is cleared
+        ``"post_clear"``
+            Sent *after* the relation is cleared
+
+    ``reverse``
+        Indicates which side of the relation is updated (i.e., if it is the
+        forward or reverse relation that is being modified).
+
+    ``model``
+        The class of the objects that are added to, removed from or cleared
+        from the relation.
+
+    ``pk_set``
+        For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove``
+        actions, this is a list of primary key values that have been added to
+        or removed from the relation.
+
+        For the ``pre_clear`` and ``post_clear`` actions, this is ``None``.
+
+For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled
+like this:
+
+.. code-block:: python
+
+    class Topping(models.Model):
+        # ...
+
+    class Pizza(models.Model):
+        # ...
+        toppings = models.ManyToManyField(Topping)
+
+If we would do something like this:
+
+.. code-block:: python
+
+    >>> p = Pizza.object.create(...)
+    >>> t = Topping.objects.create(...)
+    >>> p.toppings.add(t)
+
+the arguments sent to a :data:`m2m_changed` handler would be:
+
+    ==============  ============================================================
+    Argument        Value
+    ==============  ============================================================
+    ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)
+
+    ``instance``    ``p`` (the ``Pizza`` instance being modified)
+
+    ``action``      ``"pre_add"`` (followed by a separate signal with ``"post_add"``)
+
+    ``reverse``     ``False`` (``Pizza`` contains the :class:`ManyToManyField`,
+                    so this call modifies the forward relation)
+
+    ``model``       ``Topping`` (the class of the objects added to the
+                    ``Pizza``)
+
+    ``pk_set``      ``[t.id]`` (since only ``Topping t`` was added to the relation)
+    ==============  ============================================================
+
+And if we would then do something like this:
+
+.. code-block:: python
+
+    >>> t.pizza_set.remove(p)
+
+the arguments sent to a :data:`m2m_changed` handler would be:
+
+    ==============  ============================================================
+    Argument        Value
+    ==============  ============================================================
+    ``sender``      ``Pizza.toppings.through`` (the intermediate m2m class)
+
+    ``instance``    ``t`` (the ``Topping`` instance being modified)
+
+    ``action``      ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``)
+
+    ``reverse``     ``True`` (``Pizza`` contains the :class:`ManyToManyField`,
+                    so this call modifies the reverse relation)
+
+    ``model``       ``Pizza`` (the class of the objects removed from the
+                    ``Topping``)
+
+    ``pk_set``      ``[p.id]`` (since only ``Pizza p`` was removed from the
+                    relation)
+    ==============  ============================================================
+
+class_prepared
+--------------
+
+.. data:: django.db.models.signals.class_prepared
+   :module:
+
+Sent whenever a model class has been "prepared" -- that is, once model has
+been defined and registered with Django's model system. Django uses this
+signal internally; it's not generally used in third-party applications.
+
+Arguments that are sent with this signal:
+
+``sender``
+    The model class which was just prepared.
+
+Management signals
+==================
+
+Signals sent by :doc:`django-admin </ref/django-admin>`.
+
+post_syncdb
+-----------
+
+.. data:: django.db.models.signals.post_syncdb
+   :module:
+
+Sent by :djadmin:`syncdb` after it installs an application.
+
+Any handlers that listen to this signal need to be written in a particular
+place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If
+handlers are registered anywhere else they may not be loaded by
+:djadmin:`syncdb`.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The ``models`` module that was just installed. That is, if
+        :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``,
+        ``sender`` will be the ``foo.bar.myapp.models`` module.
+
+    ``app``
+        Same as ``sender``.
+
+    ``created_models``
+        A list of the model classes from any app which :djadmin:`syncdb` has
+        created so far.
+
+    ``verbosity``
+        Indicates how much information manage.py is printing on screen. See
+        the :djadminopt:`--verbosity` flag for details.
+
+        Functions which listen for :data:`post_syncdb` should adjust what they
+        output to the screen based on the value of this argument.
+
+    ``interactive``
+        If ``interactive`` is ``True``, it's safe to prompt the user to input
+        things on the command line. If ``interactive`` is ``False``, functions
+        which listen for this signal should not try to prompt for anything.
+
+        For example, the :mod:`django.contrib.auth` app only prompts to create a
+        superuser when ``interactive`` is ``True``.
+
+Request/response signals
+========================
+
+.. module:: django.core.signals
+   :synopsis: Core signals sent by the request/response system.
+
+Signals sent by the core framework when processing a request.
+
+request_started
+---------------
+
+.. data:: django.core.signals.request_started
+   :module:
+
+Sent when Django begins processing an HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class -- i.e.
+        :class:`django.core.handlers.modpython.ModPythonHandler` or
+        :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled
+        the request.
+
+request_finished
+----------------
+
+.. data:: django.core.signals.request_finished
+   :module:
+
+Sent when Django finishes processing an HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class, as above.
+
+got_request_exception
+---------------------
+
+.. data:: django.core.signals.got_request_exception
+   :module:
+
+This signal is sent whenever Django encounters an exception while processing an incoming HTTP request.
+
+Arguments sent with this signal:
+
+    ``sender``
+        The handler class, as above.
+
+    ``request``
+        The :class:`~django.http.HttpRequest` object.
+
+Test signals
+============
+
+.. module:: django.test.signals
+   :synopsis: Signals sent during testing.
+
+Signals only sent when :doc:`running tests </topics/testing>`.
+
+template_rendered
+-----------------
+
+.. data:: django.test.signals.template_rendered
+   :module:
+
+Sent when the test system renders a template. This signal is not emitted during
+normal operation of a Django server -- it is only available during testing.
+
+Arguments sent with this signal:
+
+    sender
+        The :class:`~django.template.Template` object which was rendered.
+
+    template
+        Same as sender
+
+    context
+        The :class:`~django.template.Context` with which the template was
+        rendered.
+
+Database Wrappers
+=================
+
+.. module:: django.db.backends
+   :synopsis: Core signals sent by the database wrapper.
+
+Signals sent by the database wrapper when a database connection is
+initiated.
+
+connection_created
+------------------
+
+.. data:: django.db.backends.signals.connection_created
+   :module:
+
+.. versionadded:: 1.1
+
+.. versionchanged:: 1.2
+   The connection argument was added
+
+Sent when the database wrapper makes the initial connection to the
+database.  This is particularly useful if you'd like to send any post
+connection commands to the SQL backend.
+
+Arguments sent with this signal:
+
+    sender
+        The database wrapper class -- i.e.
+        :class: `django.db.backends.postgresql_psycopg2.DatabaseWrapper` or
+        :class: `django.db.backends.mysql.DatabaseWrapper`, etc.
+
+    connection
+        The database connection that was opened. This can be used in a
+        multiple-database configuration to differentiate connection signals
+        from different databases.
diff --git a/parts/django/docs/ref/templates/api.txt b/parts/django/docs/ref/templates/api.txt
new file mode 100644
index 0000000..1111869
--- /dev/null
+++ b/parts/django/docs/ref/templates/api.txt
@@ -0,0 +1,815 @@
+====================================================
+The Django template language: For Python programmers
+====================================================
+
+This document explains the Django template system from a technical
+perspective -- how it works and how to extend it. If you're just looking for
+reference on the language syntax, see :doc:`/topics/templates`.
+
+If you're looking to use the Django template system as part of another
+application -- i.e., without the rest of the framework -- make sure to read
+the `configuration`_ section later in this document.
+
+.. _configuration: `configuring the template system in standalone mode`_
+
+Basics
+======
+
+A **template** is a text document, or a normal Python string, that is marked-up
+using the Django template language. A template can contain **block tags** or
+**variables**.
+
+A **block tag** is a symbol within a template that does something.
+
+This definition is deliberately vague. For example, a block tag can output
+content, serve as a control structure (an "if" statement or "for" loop), grab
+content from a database or enable access to other template tags.
+
+Block tags are surrounded by ``"{%"`` and ``"%}"``.
+
+Example template with block tags:
+
+.. code-block:: html+django
+
+    {% if is_logged_in %}Thanks for logging in!{% else %}Please log in.{% endif %}
+
+A **variable** is a symbol within a template that outputs a value.
+
+Variable tags are surrounded by ``"{{"`` and ``"}}"``.
+
+Example template with variables:
+
+.. code-block:: html+django
+
+    My first name is {{ first_name }}. My last name is {{ last_name }}.
+
+A **context** is a "variable name" -> "variable value" mapping that is passed
+to a template.
+
+A template **renders** a context by replacing the variable "holes" with values
+from the context and executing all block tags.
+
+Using the template system
+=========================
+
+.. class:: django.template.Template
+
+Using the template system in Python is a two-step process:
+
+    * First, you compile the raw template code into a ``Template`` object.
+    * Then, you call the ``render()`` method of the ``Template`` object with a
+      given context.
+
+Compiling a string
+------------------
+
+The easiest way to create a ``Template`` object is by instantiating it
+directly. The class lives at :class:`django.template.Template`. The constructor
+takes one argument -- the raw template code::
+
+    >>> from django.template import Template
+    >>> t = Template("My name is {{ my_name }}.")
+    >>> print t
+    <django.template.Template instance>
+
+.. admonition:: Behind the scenes
+
+    The system only parses your raw template code once -- when you create the
+    ``Template`` object. From then on, it's stored internally as a "node"
+    structure for performance.
+
+    Even the parsing itself is quite fast. Most of the parsing happens via a
+    single call to a single, short, regular expression.
+
+Rendering a context
+-------------------
+
+.. method:: render(context)
+
+Once you have a compiled ``Template`` object, you can render a context -- or
+multiple contexts -- with it. The ``Context`` class lives at
+:class:`django.template.Context`, and the constructor takes two (optional)
+arguments:
+
+    * A dictionary mapping variable names to variable values.
+
+    * The name of the current application. This application name is used
+      to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`.
+      If you're not using namespaced URLs, you can ignore this argument.
+
+Call the ``Template`` object's ``render()`` method with the context to "fill" the
+template::
+
+    >>> from django.template import Context, Template
+    >>> t = Template("My name is {{ my_name }}.")
+
+    >>> c = Context({"my_name": "Adrian"})
+    >>> t.render(c)
+    "My name is Adrian."
+
+    >>> c = Context({"my_name": "Dolores"})
+    >>> t.render(c)
+    "My name is Dolores."
+
+Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
+or a dot.
+
+Dots have a special meaning in template rendering. A dot in a variable name
+signifies **lookup**. Specifically, when the template system encounters a dot
+in a variable name, it tries the following lookups, in this order:
+
+    * Dictionary lookup. Example: ``foo["bar"]``
+    * Attribute lookup. Example: ``foo.bar``
+    * Method call. Example: ``foo.bar()``
+    * List-index lookup. Example: ``foo[bar]``
+
+The template system uses the first lookup type that works. It's short-circuit
+logic.
+
+Here are a few examples::
+
+    >>> from django.template import Context, Template
+    >>> t = Template("My name is {{ person.first_name }}.")
+    >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
+    >>> t.render(Context(d))
+    "My name is Joe."
+
+    >>> class PersonClass: pass
+    >>> p = PersonClass()
+    >>> p.first_name = "Ron"
+    >>> p.last_name = "Nasty"
+    >>> t.render(Context({"person": p}))
+    "My name is Ron."
+
+    >>> class PersonClass2:
+    ...     def first_name(self):
+    ...         return "Samantha"
+    >>> p = PersonClass2()
+    >>> t.render(Context({"person": p}))
+    "My name is Samantha."
+
+    >>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
+    >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
+    >>> t.render(c)
+    "The first stooge in the list is Larry."
+
+Method lookups are slightly more complex than the other lookup types. Here are
+some things to keep in mind:
+
+    * If, during the method lookup, a method raises an exception, the exception
+      will be propagated, unless the exception has an attribute
+      ``silent_variable_failure`` whose value is ``True``. If the exception
+      *does* have a ``silent_variable_failure`` attribute, the variable will
+      render as an empty string. Example::
+
+        >>> t = Template("My name is {{ person.first_name }}.")
+        >>> class PersonClass3:
+        ...     def first_name(self):
+        ...         raise AssertionError, "foo"
+        >>> p = PersonClass3()
+        >>> t.render(Context({"person": p}))
+        Traceback (most recent call last):
+        ...
+        AssertionError: foo
+
+        >>> class SilentAssertionError(Exception):
+        ...     silent_variable_failure = True
+        >>> class PersonClass4:
+        ...     def first_name(self):
+        ...         raise SilentAssertionError
+        >>> p = PersonClass4()
+        >>> t.render(Context({"person": p}))
+        "My name is ."
+
+      Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the
+      base class for all Django database API ``DoesNotExist`` exceptions, has
+      ``silent_variable_failure = True``. So if you're using Django templates
+      with Django model objects, any ``DoesNotExist`` exception will fail
+      silently.
+
+    * A method call will only work if the method has no required arguments.
+      Otherwise, the system will move to the next lookup type (list-index
+      lookup).
+
+    * Obviously, some methods have side effects, and it'd be either foolish or
+      a security hole to allow the template system to access them.
+
+      A good example is the :meth:`~django.db.models.Model.delete` method on
+      each Django model object. The template system shouldn't be allowed to do
+      something like this::
+
+        I will now delete this valuable data. {{ data.delete }}
+
+      To prevent this, set a function attribute ``alters_data`` on the method.
+      The template system won't execute a method if the method has
+      ``alters_data=True`` set. The dynamically-generated
+      :meth:`~django.db.models.Model.delete` and
+      :meth:`~django.db.models.Model.save` methods on Django model objects get
+      ``alters_data=True`` automatically. Example::
+
+        def sensitive_function(self):
+            self.database_record.delete()
+        sensitive_function.alters_data = True
+
+.. _invalid-template-variables:
+
+How invalid variables are handled
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, if a variable doesn't exist, the template system inserts the
+value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to
+``''`` (the empty string) by default.
+
+Filters that are applied to an invalid variable will only be applied if
+:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If
+:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable
+filters will be ignored.
+
+This behavior is slightly different for the ``if``, ``for`` and ``regroup``
+template tags. If an invalid variable is provided to one of these template
+tags, the variable will be interpreted as ``None``. Filters are always
+applied to invalid variables within these template tags.
+
+If :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will
+be replaced with the name of the invalid variable.
+
+.. admonition:: For debug purposes only!
+
+    While :setting:`TEMPLATE_STRING_IF_INVALID` can be a useful debugging tool,
+    it is a bad idea to turn it on as a 'development default'.
+
+    Many templates, including those in the Admin site, rely upon the
+    silence of the template system when a non-existent variable is
+    encountered. If you assign a value other than ``''`` to
+    :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering
+    problems with these templates and sites.
+
+    Generally, :setting:`TEMPLATE_STRING_IF_INVALID` should only be enabled
+    in order to debug a specific template problem, then cleared
+    once debugging is complete.
+
+Playing with Context objects
+----------------------------
+
+.. class:: django.template.Context
+
+Most of the time, you'll instantiate ``Context`` objects by passing in a
+fully-populated dictionary to ``Context()``. But you can add and delete items
+from a ``Context`` object once it's been instantiated, too, using standard
+dictionary syntax::
+
+    >>> c = Context({"foo": "bar"})
+    >>> c['foo']
+    'bar'
+    >>> del c['foo']
+    >>> c['foo']
+    ''
+    >>> c['newvariable'] = 'hello'
+    >>> c['newvariable']
+    'hello'
+
+.. method:: pop()
+.. method:: push()
+.. exception:: django.template.ContextPopException
+
+A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it.
+If you ``pop()`` too much, it'll raise
+``django.template.ContextPopException``::
+
+    >>> c = Context()
+    >>> c['foo'] = 'first level'
+    >>> c.push()
+    >>> c['foo'] = 'second level'
+    >>> c['foo']
+    'second level'
+    >>> c.pop()
+    >>> c['foo']
+    'first level'
+    >>> c['foo'] = 'overwritten'
+    >>> c['foo']
+    'overwritten'
+    >>> c.pop()
+    Traceback (most recent call last):
+    ...
+    django.template.ContextPopException
+
+.. method:: update(other_dict)
+
+In addition to ``push()`` and ``pop()``, the ``Context``
+object also defines an ``update()`` method. This works like ``push()``
+but takes a dictionary as an argument and pushes that dictionary onto
+the stack instead of an empty one.
+
+    >>> c = Context()
+    >>> c['foo'] = 'first level'
+    >>> c.update({'foo': 'updated'})
+    {'foo': 'updated'}
+    >>> c['foo']
+    'updated'
+    >>> c.pop()
+    {'foo': 'updated'}
+    >>> c['foo']
+    'first level'
+
+Using a ``Context`` as a stack comes in handy in some custom template tags, as
+you'll see below.
+
+.. _subclassing-context-requestcontext:
+
+Subclassing Context: RequestContext
+-----------------------------------
+
+Django comes with a special ``Context`` class,
+``django.template.RequestContext``, that acts slightly differently than the
+normal ``django.template.Context``. The first difference is that it takes an
+:class:`~django.http.HttpRequest` as its first argument. For example::
+
+    c = RequestContext(request, {
+        'foo': 'bar',
+    })
+
+The second difference is that it automatically populates the context with a few
+variables, according to your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+The :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting is a tuple of callables --
+called **context processors** -- that take a request object as their argument
+and return a dictionary of items to be merged into the context. By default,
+:setting:`TEMPLATE_CONTEXT_PROCESSORS` is set to::
+
+    ("django.contrib.auth.context_processors.auth",
+    "django.core.context_processors.debug",
+    "django.core.context_processors.i18n",
+    "django.core.context_processors.media",
+    "django.contrib.messages.context_processors.messages")
+
+.. versionadded:: 1.2
+   In addition to these, ``RequestContext`` always uses
+   ``django.core.context_processors.csrf``.  This is a security
+   related context processor required by the admin and other contrib apps, and,
+   in case of accidental misconfiguration, it is deliberately hardcoded in and
+   cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+.. versionadded:: 1.2
+   The ``'messages'`` context processor was added.  For more information, see
+   the :doc:`messages documentation </ref/contrib/messages>`.
+
+.. versionchanged:: 1.2
+    The auth context processor was moved in this release from its old location
+    ``django.core.context_processors.auth`` to
+    ``django.contrib.auth.context_processors.auth``.
+
+Each processor is applied in order. That means, if one processor adds a
+variable to the context and a second processor adds a variable with the same
+name, the second will override the first. The default processors are explained
+below.
+
+.. admonition:: When context processors are applied
+
+    When you use ``RequestContext``, the variables you supply directly
+    are added first, followed any variables supplied by context
+    processors. This means that a context processor may overwrite a
+    variable you've supplied, so take care to avoid variable names
+    which overlap with those supplied by your context processors.
+
+Also, you can give ``RequestContext`` a list of additional processors, using the
+optional, third positional argument, ``processors``. In this example, the
+``RequestContext`` instance gets a ``ip_address`` variable::
+
+    def ip_address_processor(request):
+        return {'ip_address': request.META['REMOTE_ADDR']}
+
+    def some_view(request):
+        # ...
+        c = RequestContext(request, {
+            'foo': 'bar',
+        }, [ip_address_processor])
+        return HttpResponse(t.render(c))
+
+.. note::
+    If you're using Django's ``render_to_response()`` shortcut to populate a
+    template with the contents of a dictionary, your template will be passed a
+    ``Context`` instance by default (not a ``RequestContext``). To use a
+    ``RequestContext`` in your template rendering, pass an optional third
+    argument to ``render_to_response()``: a ``RequestContext``
+    instance. Your code might look like this::
+
+        def some_view(request):
+            # ...
+            return render_to_response('my_template.html',
+                                      my_data_dictionary,
+                                      context_instance=RequestContext(request))
+
+Here's what each of the default processors does:
+
+django.contrib.auth.context_processors.auth
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these three variables:
+
+    * ``user`` -- An ``auth.User`` instance representing the currently
+      logged-in user (or an ``AnonymousUser`` instance, if the client isn't
+      logged in).
+
+    * ``messages`` -- A list of messages (as strings) that have been set
+      via the :doc:`messages framework </ref/contrib/messages>`.
+
+    * ``perms`` -- An instance of
+      ``django.core.context_processors.PermWrapper``, representing the
+      permissions that the currently logged-in user has.
+
+.. versionchanged:: 1.2
+    This context processor was moved in this release from
+    ``django.core.context_processors.auth`` to its current location.
+
+.. versionchanged:: 1.2
+   Prior to version 1.2, the ``messages`` variable was a lazy accessor for
+   ``user.get_and_delete_messages()``. It has been changed to include any
+   messages added via the :doc:`messages framework </ref/contrib/messages>`.
+
+django.core.context_processors.debug
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these two variables -- but only if your
+:setting:`DEBUG` setting is set to ``True`` and the request's IP address
+(``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting:
+
+    * ``debug`` -- ``True``. You can use this in templates to test whether
+      you're in :setting:`DEBUG` mode.
+    * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries,
+      representing every SQL query that has happened so far during the request
+      and how long it took. The list is in order by query.
+
+django.core.context_processors.i18n
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain these two variables:
+
+    * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting.
+    * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise,
+      the value of the :setting:`LANGUAGE_CODE` setting.
+
+See :doc:`/topics/i18n/index` for more.
+
+django.core.context_processors.media
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a variable ``MEDIA_URL``, providing the
+value of the :setting:`MEDIA_URL` setting.
+
+django.core.context_processors.csrf
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+This processor adds a token that is needed by the ``csrf_token`` template tag
+for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`.
+
+django.core.context_processors.request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a variable ``request``, which is the current
+:class:`~django.http.HttpRequest`. Note that this processor is not enabled by default;
+you'll have to activate it.
+
+django.contrib.messages.context_processors.messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
+``RequestContext`` will contain a single additional variable:
+
+    * ``messages`` -- A list of messages (as strings) that have been set
+      via the user model (using ``user.message_set.create``) or through
+      the :doc:`messages framework </ref/contrib/messages>`.
+
+.. versionadded:: 1.2
+   This template context variable was previously supplied by the ``'auth'``
+   context processor.  For backwards compatibility the ``'auth'`` context
+   processor will continue to supply the ``messages`` variable until Django
+   1.4.  If you use the ``messages`` variable, your project will work with
+   either (or both) context processors, but it is recommended to add
+   ``django.contrib.messages.context_processors.messages`` so your project
+   will be prepared for the future upgrade.
+
+Writing your own context processors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A context processor has a very simple interface: It's just a Python function
+that takes one argument, an :class:`~django.http.HttpRequest` object, and
+returns a dictionary that gets added to the template context. Each context
+processor *must* return a dictionary.
+
+Custom context processors can live anywhere in your code base. All Django cares
+about is that your custom context processors are pointed-to by your
+:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
+
+Loading templates
+-----------------
+
+Generally, you'll store templates in files on your filesystem rather than using
+the low-level ``Template`` API yourself. Save templates in a directory
+specified as a **template directory**.
+
+Django searches for template directories in a number of places, depending on
+your template-loader settings (see "Loader types" below), but the most basic
+way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
+setting.
+
+The TEMPLATE_DIRS setting
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tell Django what your template directories are by using the
+:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
+list or tuple of strings that contain full paths to your template
+directory(ies). Example::
+
+    TEMPLATE_DIRS = (
+        "/home/html/templates/lawrence.com",
+        "/home/html/templates/default",
+    )
+
+Your templates can go anywhere you want, as long as the directories and
+templates are readable by the Web server. They can have any extension you want,
+such as ``.html`` or ``.txt``, or they can have no extension at all.
+
+Note that these paths should use Unix-style forward slashes, even on Windows.
+
+.. _ref-templates-api-the-python-api:
+
+The Python API
+~~~~~~~~~~~~~~
+
+Django has two ways to load templates from files:
+
+.. function:: django.template.loader.get_template(template_name)
+
+    ``get_template`` returns the compiled template (a ``Template`` object) for
+    the template with the given name. If the template doesn't exist, it raises
+    ``django.template.TemplateDoesNotExist``.
+
+.. function:: django.template.loader.select_template(template_name_list)
+
+    ``select_template`` is just like ``get_template``, except it takes a list
+    of template names. Of the list, it returns the first template that exists.
+
+For example, if you call ``get_template('story_detail.html')`` and have the
+above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for,
+in order:
+
+    * ``/home/html/templates/lawrence.com/story_detail.html``
+    * ``/home/html/templates/default/story_detail.html``
+
+If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``,
+here's what Django will look for:
+
+    * ``/home/html/templates/lawrence.com/story_253_detail.html``
+    * ``/home/html/templates/default/story_253_detail.html``
+    * ``/home/html/templates/lawrence.com/story_detail.html``
+    * ``/home/html/templates/default/story_detail.html``
+
+When Django finds a template that exists, it stops looking.
+
+.. admonition:: Tip
+
+    You can use ``select_template()`` for super-flexible "templatability." For
+    example, if you've written a news story and want some stories to have
+    custom templates, use something like
+    ``select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])``.
+    That'll allow you to use a custom template for an individual story, with a
+    fallback template for stories that don't have custom templates.
+
+Using subdirectories
+~~~~~~~~~~~~~~~~~~~~
+
+It's possible -- and preferable -- to organize templates in subdirectories of
+the template directory. The convention is to make a subdirectory for each
+Django app, with subdirectories within those subdirectories as needed.
+
+Do this for your own sanity. Storing all templates in the root level of a
+single directory gets messy.
+
+To load a template that's within a subdirectory, just use a slash, like so::
+
+    get_template('news/story_detail.html')
+
+Using the same :setting:`TEMPLATE_DIRS` setting from above, this example
+``get_template()`` call will attempt to load the following templates:
+
+    * ``/home/html/templates/lawrence.com/news/story_detail.html``
+    * ``/home/html/templates/default/news/story_detail.html``
+
+.. _template-loaders:
+
+Loader types
+~~~~~~~~~~~~
+
+By default, Django uses a filesystem-based template loader, but Django comes
+with a few other template loaders, which know how to load templates from other
+sources.
+
+Some of these other loaders are disabled by default, but you can activate them
+by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
+should be a tuple of strings, where each string represents a template loader.
+Here are the template loaders that come with Django:
+
+``django.template.loaders.filesystem.Loader``
+    Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
+    This loader is enabled by default.
+
+``django.template.loaders.app_directories.Loader``
+    Loads templates from Django apps on the filesystem. For each app in
+    :setting:`INSTALLED_APPS`, the loader looks for a ``templates``
+    subdirectory. If the directory exists, Django looks for templates in there.
+
+    This means you can store templates with your individual apps. This also
+    makes it easy to distribute Django apps with default templates.
+
+    For example, for this setting::
+
+        INSTALLED_APPS = ('myproject.polls', 'myproject.music')
+
+    ...then ``get_template('foo.html')`` will look for templates in these
+    directories, in this order:
+
+        * ``/path/to/myproject/polls/templates/foo.html``
+        * ``/path/to/myproject/music/templates/foo.html``
+
+    Note that the loader performs an optimization when it is first imported: It
+    caches a list of which :setting:`INSTALLED_APPS` packages have a
+    ``templates`` subdirectory.
+
+    This loader is enabled by default.
+
+``django.template.loaders.eggs.Loader``
+    Just like ``app_directories`` above, but it loads templates from Python
+    eggs rather than from the filesystem.
+
+    This loader is disabled by default.
+
+``django.template.loaders.cached.Loader``
+    By default, the templating system will read and compile your templates every
+    time they need to be rendered. While the Django templating system is quite
+    fast, the overhead from reading and compiling templates can add up.
+
+    The cached template loader is a class-based loader that you configure with
+    a list of other loaders that it should wrap. The wrapped loaders are used to
+    locate unknown templates when they are first encountered. The cached loader
+    then stores the compiled ``Template`` in memory. The cached ``Template``
+    instance is returned for subsequent requests to load the same template.
+
+    For example, to enable template caching with the ``filesystem`` and
+    ``app_directories`` template loaders you might use the following settings::
+
+        TEMPLATE_LOADERS = (
+            ('django.template.loaders.cached.Loader', (
+                'django.template.loaders.filesystem.Loader',
+                'django.template.loaders.app_directories.Loader',
+            )),
+        )
+
+    .. note::
+        All of the built-in Django template tags are safe to use with the cached
+        loader, but if you're using custom template tags that come from third
+        party packages, or that you wrote yourself, you should ensure that the
+        ``Node`` implementation for each tag is thread-safe. For more
+        information, see
+        :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
+
+    This loader is disabled by default.
+
+Django uses the template loaders in order according to the
+:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
+match.
+
+The ``render_to_string`` shortcut
+===================================
+
+.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None)
+
+To cut down on the repetitive nature of loading and rendering
+templates, Django provides a shortcut function which largely
+automates the process: ``render_to_string()`` in
+:mod:`django.template.loader`, which loads a template, renders it and
+returns the resulting string::
+
+    from django.template.loader import render_to_string
+    rendered = render_to_string('my_template.html', { 'foo': 'bar' })
+
+The ``render_to_string`` shortcut takes one required argument --
+``template_name``, which should be the name of the template to load
+and render (or a list of template names, in which case Django will use
+the first template in the list that exists) -- and two optional arguments:
+
+    dictionary
+        A dictionary to be used as variables and values for the
+        template's context. This can also be passed as the second
+        positional argument.
+
+    context_instance
+        An instance of ``Context`` or a subclass (e.g., an instance of
+        ``RequestContext``) to use as the template's context. This can
+        also be passed as the third positional argument.
+
+See also the :func:`~django.shortcuts.render_to_response()` shortcut, which
+calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse`
+suitable for returning directly from a view.
+
+Configuring the template system in standalone mode
+==================================================
+
+.. note::
+
+    This section is only of interest to people trying to use the template
+    system as an output component in another application. If you're using the
+    template system as part of a Django application, nothing here applies to
+    you.
+
+Normally, Django will load all the configuration information it needs from its
+own default configuration file, combined with the settings in the module given
+in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're
+using the template system independently of the rest of Django, the environment
+variable approach isn't very convenient, because you probably want to configure
+the template system in line with the rest of your application rather than
+dealing with settings files and pointing to them via environment variables.
+
+To solve this problem, you need to use the manual configuration option described
+in :ref:`settings-without-django-settings-module`. Simply import the appropriate
+pieces of the templating system and then, *before* you call any of the
+templating functions, call :func:`django.conf.settings.configure()` with any
+settings you wish to specify. You might want to consider setting at least
+:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
+:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
+and :setting:`TEMPLATE_DEBUG`. All available settings are described in the
+:doc:`settings documentation </ref/settings>`, and any setting starting with
+``TEMPLATE_`` is of obvious interest.
+
+.. _topic-template-alternate-language:
+
+Using an alternative template language
+======================================
+
+.. versionadded:: 1.2
+
+The Django ``Template`` and ``Loader`` classes implement a simple API for
+loading and rendering templates. By providing some simple wrapper classes that
+implement this API we can use third party template systems like `Jinja2
+<http://jinja.pocoo.org/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
+allows us to use third-party template libraries without giving up useful Django
+features like the Django ``Context`` object and handy shortcuts like
+``render_to_response()``.
+
+The core component of the Django templating system is the ``Template`` class.
+This class has a very simple interface: it has a constructor that takes a single
+positional argument specifying the template string, and a ``render()`` method
+that takes a :class:`~django.template.Context` object and returns a string
+containing the rendered response.
+
+Suppose we're using a template language that defines a ``Template`` object with
+a ``render()`` method that takes a dictionary rather than a ``Context`` object.
+We can write a simple wrapper that implements the Django ``Template`` interface::
+
+    import some_template_language
+    class Template(some_template_language.Template):
+        def render(self, context):
+            # flatten the Django Context into a single dictionary.
+            context_dict = {}
+            for d in context.dicts:
+                context_dict.update(d)
+            return super(Template, self).render(context_dict)
+
+That's all that's required to make our fictional ``Template`` class compatible
+with the Django loading and rendering system!
+
+The next step is to write a ``Loader`` class that returns instances of our custom
+template class instead of the default :class:`~django.template.Template`. Custom ``Loader``
+classes should inherit from ``django.template.loader.BaseLoader`` and override
+the ``load_template_source()`` method, which takes a ``template_name`` argument,
+loads the template from disk (or elsewhere), and returns a tuple:
+``(template_string, template_origin)``.
+
+The ``load_template()`` method of the ``Loader`` class retrieves the template
+string by calling ``load_template_source()``, instantiates a ``Template`` from
+the template source, and returns a tuple: ``(template, template_origin)``. Since
+this is the method that actually instantiates the ``Template``, we'll need to
+override it to use our custom template class instead. We can inherit from the
+builtin :class:`django.template.loaders.app_directories.Loader` to take advantage
+of the ``load_template_source()`` method implemented there::
+
+    from django.template.loaders import app_directories
+    class Loader(app_directories.Loader):
+        is_usable = True
+
+        def load_template(self, template_name, template_dirs=None):
+            source, origin = self.load_template_source(template_name, template_dirs)
+            template = Template(source)
+            return template, origin
+
+Finally, we need to modify our project settings, telling Django to use our custom
+loader. Now we can write all of our templates in our alternative template
+language while continuing to use the rest of the Django templating system.
diff --git a/parts/django/docs/ref/templates/builtins.txt b/parts/django/docs/ref/templates/builtins.txt
new file mode 100644
index 0000000..44bbc37
--- /dev/null
+++ b/parts/django/docs/ref/templates/builtins.txt
@@ -0,0 +1,2107 @@
+==================================
+Built-in template tags and filters
+==================================
+
+This document describes Django's built-in template tags and filters. It is
+recommended that you use the :doc:`automatic documentation
+</ref/contrib/admin/admindocs>`, if available, as this will also include
+documentation for any custom tags or filters installed.
+
+.. _ref-templates-builtins-tags:
+
+Built-in tag reference
+----------------------
+
+.. highlightlang:: html+django
+
+.. templatetag:: autoescape
+
+autoescape
+~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+Control the current auto-escaping behavior. This tag takes either ``on`` or
+``off`` as an argument and that determines whether auto-escaping is in effect
+inside the block. The block is closed with an ``endautoescape`` ending tag.
+
+When auto-escaping is in effect, all variable content has HTML escaping applied
+to it before placing the result into the output (but after any filters have
+been applied). This is equivalent to manually applying the ``escape`` filter
+to each variable.
+
+The only exceptions are variables that are already marked as "safe" from
+escaping, either by the code that populated the variable, or because it has had
+the ``safe`` or ``escape`` filters applied.
+
+Sample usage::
+
+    {% autoescape on %}
+        {{ body }}
+    {% endautoescape %}
+
+.. templatetag:: block
+
+block
+~~~~~
+
+Define a block that can be overridden by child templates. See
+:ref:`Template inheritance <template-inheritance>` for more information.
+
+.. templatetag:: comment
+
+comment
+~~~~~~~
+
+Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
+
+.. templatetag:: csrf_token
+
+csrf_token
+~~~~~~~~~~
+
+.. versionadded:: 1.1.2
+
+In the Django 1.1.X series, this is a no-op tag that returns an empty string for
+future compatibility purposes.  In Django 1.2 and later, it is used for CSRF
+protection, as described in the documentation for :doc:`Cross Site Request
+Forgeries </ref/contrib/csrf>`.
+
+.. templatetag:: cycle
+
+cycle
+~~~~~
+
+.. versionchanged:: 1.0
+    Cycle among the given strings or variables each time this tag is encountered.
+
+Within a loop, cycles among the given strings each time through the
+loop::
+
+    {% for o in some_list %}
+        <tr class="{% cycle 'row1' 'row2' %}">
+            ...
+        </tr>
+    {% endfor %}
+
+You can use variables, too. For example, if you have two template variables,
+``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this::
+
+    {% for o in some_list %}
+        <tr class="{% cycle rowvalue1 rowvalue2 %}">
+            ...
+        </tr>
+    {% endfor %}
+
+Yes, you can mix variables and strings::
+
+    {% for o in some_list %}
+        <tr class="{% cycle 'row1' rowvalue2 'row3' %}">
+            ...
+        </tr>
+    {% endfor %}
+
+In some cases you might want to refer to the next value of a cycle from
+outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using
+"as", like this::
+
+    {% cycle 'row1' 'row2' as rowcolors %}
+
+From then on, you can insert the current value of the cycle wherever you'd like
+in your template::
+
+    <tr class="{% cycle rowcolors %}">...</tr>
+    <tr class="{% cycle rowcolors %}">...</tr>
+
+You can use any number of values in a ``{% cycle %}`` tag, separated by spaces.
+Values enclosed in single (``'``) or double quotes (``"``) are treated as
+string literals, while values without quotes are treated as template variables.
+
+Note that the variables included in the cycle will not be escaped.
+This is because template tags do not escape their content. Any HTML or
+Javascript code contained in the printed variable will be rendered
+as-is, which could potentially lead to security issues.
+
+If you need to escape the variables in the cycle, you must do so
+explicitly::
+
+    {% filter force_escape %}
+        {% cycle var1 var2 var3 %}
+    {% endfilter %}
+
+For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior
+old syntax from previous Django versions. You shouldn't use this in any new
+projects, but for the sake of the people who are still using it, here's what it
+looks like::
+
+    {% cycle row1,row2,row3 %}
+
+In this syntax, each value gets interpreted as a literal string, and there's no
+way to specify variable values. Or literal commas. Or spaces. Did we mention
+you shouldn't use this syntax in any new projects?
+
+.. templatetag:: debug
+
+debug
+~~~~~
+
+Output a whole load of debugging information, including the current context and
+imported modules.
+
+.. templatetag:: extends
+
+extends
+~~~~~~~
+
+Signal that this template extends a parent template.
+
+This tag can be used in two ways:
+
+   * ``{% extends "base.html" %}`` (with quotes) uses the literal value
+     ``"base.html"`` as the name of the parent template to extend.
+
+   * ``{% extends variable %}`` uses the value of ``variable``. If the variable
+     evaluates to a string, Django will use that string as the name of the
+     parent template. If the variable evaluates to a ``Template`` object,
+     Django will use that object as the parent template.
+
+See :ref:`template-inheritance` for more information.
+
+.. templatetag:: filter
+
+filter
+~~~~~~
+
+Filter the contents of the variable through variable filters.
+
+Filters can also be piped through each other, and they can have arguments --
+just like in variable syntax.
+
+Sample usage::
+
+    {% filter force_escape|lower %}
+        This text will be HTML-escaped, and will appear in all lowercase.
+    {% endfilter %}
+
+.. templatetag:: firstof
+
+firstof
+~~~~~~~
+
+Outputs the first variable passed that is not False, without escaping.
+
+Outputs nothing if all the passed variables are False.
+
+Sample usage::
+
+    {% firstof var1 var2 var3 %}
+
+This is equivalent to::
+
+    {% if var1 %}
+        {{ var1|safe }}
+    {% else %}{% if var2 %}
+        {{ var2|safe }}
+    {% else %}{% if var3 %}
+        {{ var3|safe }}
+    {% endif %}{% endif %}{% endif %}
+
+You can also use a literal string as a fallback value in case all
+passed variables are False::
+
+    {% firstof var1 var2 var3 "fallback value" %}
+
+Note that the variables included in the firstof tag will not be
+escaped. This is because template tags do not escape their content.
+Any HTML or Javascript code contained in the printed variable will be
+rendered as-is, which could potentially lead to security issues.
+
+If you need to escape the variables in the firstof tag, you must do so
+explicitly::
+
+    {% filter force_escape %}
+        {% firstof var1 var2 var3 "fallback value" %}
+    {% endfilter %}
+
+.. templatetag:: for
+
+for
+~~~
+
+Loop over each item in an array.  For example, to display a list of athletes
+provided in ``athlete_list``::
+
+    <ul>
+    {% for athlete in athlete_list %}
+        <li>{{ athlete.name }}</li>
+    {% endfor %}
+    </ul>
+
+You can loop over a list in reverse by using ``{% for obj in list reversed %}``.
+
+.. versionadded:: 1.0
+
+If you need to loop over a list of lists, you can unpack the values
+in each sub-list into individual variables. For example, if your context
+contains a list of (x,y) coordinates called ``points``, you could use the
+following to output the list of points::
+
+    {% for x, y in points %}
+        There is a point at {{ x }},{{ y }}
+    {% endfor %}
+
+This can also be useful if you need to access the items in a dictionary.
+For example, if your context contained a dictionary ``data``, the following
+would display the keys and values of the dictionary::
+
+    {% for key, value in data.items %}
+        {{ key }}: {{ value }}
+    {% endfor %}
+
+The for loop sets a number of variables available within the loop:
+
+    ==========================  ================================================
+    Variable                    Description
+    ==========================  ================================================
+    ``forloop.counter``         The current iteration of the loop (1-indexed)
+    ``forloop.counter0``        The current iteration of the loop (0-indexed)
+    ``forloop.revcounter``      The number of iterations from the end of the
+                                loop (1-indexed)
+    ``forloop.revcounter0``     The number of iterations from the end of the
+                                loop (0-indexed)
+    ``forloop.first``           True if this is the first time through the loop
+    ``forloop.last``            True if this is the last time through the loop
+    ``forloop.parentloop``      For nested loops, this is the loop "above" the
+                                current one
+    ==========================  ================================================
+
+for ... empty
+^^^^^^^^^^^^^
+
+.. versionadded:: 1.1
+
+The ``for`` tag can take an optional ``{% empty %}`` clause that will be
+displayed if the given array is empty or could not be found::
+
+    <ul>
+    {% for athlete in athlete_list %}
+        <li>{{ athlete.name }}</li>
+    {% empty %}
+        <li>Sorry, no athlete in this list!</li>
+    {% endfor %}
+    <ul>
+
+The above is equivalent to -- but shorter, cleaner, and possibly faster
+than -- the following::
+
+    <ul>
+      {% if athlete_list %}
+        {% for athlete in athlete_list %}
+          <li>{{ athlete.name }}</li>
+        {% endfor %}
+      {% else %}
+        <li>Sorry, no athletes in this list.</li>
+      {% endif %}
+    </ul>
+
+.. templatetag:: if
+
+if
+~~
+
+The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
+exists, is not empty, and is not a false boolean value) the contents of the
+block are output::
+
+    {% if athlete_list %}
+        Number of athletes: {{ athlete_list|length }}
+    {% else %}
+        No athletes.
+    {% endif %}
+
+In the above, if ``athlete_list`` is not empty, the number of athletes will be
+displayed by the ``{{ athlete_list|length }}`` variable.
+
+As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that
+will be displayed if the test fails.
+
+Boolean operators
+^^^^^^^^^^^^^^^^^
+
+``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or
+to negate a given variable::
+
+    {% if athlete_list and coach_list %}
+        Both athletes and coaches are available.
+    {% endif %}
+
+    {% if not athlete_list %}
+        There are no athletes.
+    {% endif %}
+
+    {% if athlete_list or coach_list %}
+        There are some athletes or some coaches.
+    {% endif %}
+
+    {% if not athlete_list or coach_list %}
+        There are no athletes or there are some coaches (OK, so
+        writing English translations of boolean logic sounds
+        stupid; it's not our fault).
+    {% endif %}
+
+    {% if athlete_list and not coach_list %}
+        There are some athletes and absolutely no coaches.
+    {% endif %}
+
+.. versionchanged:: 1.2
+
+Use of both ``and`` and ``or`` clauses within the same tag is allowed, with
+``and`` having higher precedence than ``or`` e.g.::
+
+    {% if athlete_list and coach_list or cheerleader_list %}
+
+will be interpreted like:
+
+.. code-block:: python
+
+    if (athlete_list and coach_list) or cheerleader_list
+
+Use of actual brackets in the ``if`` tag is invalid syntax.  If you need them to
+indicate precedence, you should use nested ``if`` tags.
+
+.. versionadded:: 1.2
+
+
+``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``,
+``<=``, ``>=`` and ``in`` which work as follows:
+
+
+``==`` operator
+^^^^^^^^^^^^^^^
+
+Equality. Example::
+
+    {% if somevar == "x" %}
+      This appears if variable somevar equals the string "x"
+    {% endif %}
+
+``!=`` operator
+^^^^^^^^^^^^^^^
+
+Inequality. Example::
+
+    {% if somevar != "x" %}
+      This appears if variable somevar does not equal the string "x",
+      or if somevar is not found in the context
+    {% endif %}
+
+``<`` operator
+^^^^^^^^^^^^^^
+
+Less than. Example::
+
+    {% if somevar < 100 %}
+      This appears if variable somevar is less than 100.
+    {% endif %}
+
+``>`` operator
+^^^^^^^^^^^^^^
+
+Greater than. Example::
+
+    {% if somevar > 0 %}
+      This appears if variable somevar is greater than 0.
+    {% endif %}
+
+``<=`` operator
+^^^^^^^^^^^^^^^
+
+Less than or equal to. Example::
+
+    {% if somevar <= 100 %}
+      This appears if variable somevar is less than 100 or equal to 100.
+    {% endif %}
+
+``>=`` operator
+^^^^^^^^^^^^^^^
+
+Greater than or equal to. Example::
+
+    {% if somevar >= 1 %}
+      This appears if variable somevar is greater than 1 or equal to 1.
+    {% endif %}
+
+``in`` operator
+^^^^^^^^^^^^^^^
+
+Contained within. This operator is supported by many Python containers to test
+whether the given value is in the container.  The following are some examples of
+how ``x in y`` will be interpreted::
+
+    {% if "bc" in "abcdef" %}
+      This appears since "bc" is a substring of "abcdef"
+    {% endif %}
+
+    {% if "hello" in greetings %}
+      If greetings is a list or set, one element of which is the string
+      "hello", this will appear.
+    {% endif %}
+
+    {% if user in users %}
+      If users is a QuerySet, this will appear if user is an
+      instance that belongs to the QuerySet.
+    {% endif %}
+
+``not in`` operator
+~~~~~~~~~~~~~~~~~~~~
+
+Not contained within.  This is the negation of the ``in`` operator.
+
+
+The comparison operators cannot be 'chained' like in Python or in mathematical
+notation. For example, instead of using::
+
+    {% if a > b > c %}  (WRONG)
+
+you should use::
+
+    {% if a > b and b > c %}
+
+
+Filters
+^^^^^^^
+
+You can also use filters in the ``if`` expression. For example::
+
+    {% if messages|length >= 100 %}
+       You have lots of messages today!
+    {% endif %}
+
+Complex expressions
+^^^^^^^^^^^^^^^^^^^
+
+All of the above can be combined to form complex expressions. For such
+expressions, it can be important to know how the operators are grouped when the
+expression is evaluated - that is, the precedence rules.  The precedence of the
+operators, from lowest to highest, is as follows:
+
+ * ``or``
+ * ``and``
+ * ``not``
+ * ``in``
+ * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=``
+
+(This follows Python exactly). So, for example, the following complex if tag:
+
+    {% if a == b or c == d and e %}
+
+...will be interpreted as:
+
+.. code-block:: python
+
+    (a == b) or ((c == d) and e)
+
+If you need different precedence, you will need to use nested if tags. Sometimes
+that is better for clarity anyway, for the sake of those who do not know the
+precedence rules.
+
+
+.. templatetag:: ifchanged
+
+ifchanged
+~~~~~~~~~
+
+Check if a value has changed from the last iteration of a loop.
+
+The 'ifchanged' block tag is used within a loop. It has two possible uses.
+
+1. Checks its own rendered contents against its previous state and only
+   displays the content if it has changed. For example, this displays a list of
+   days, only displaying the month if it changes::
+
+        <h1>Archive for {{ year }}</h1>
+
+        {% for date in days %}
+            {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %}
+            <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a>
+        {% endfor %}
+
+2. If given a variable, check whether that variable has changed. For
+   example, the following shows the date every time it changes, but
+   only shows the hour if both the hour and the date has changed::
+
+        {% for date in days %}
+            {% ifchanged date.date %} {{ date.date }} {% endifchanged %}
+            {% ifchanged date.hour date.date %}
+                {{ date.hour }}
+            {% endifchanged %}
+        {% endfor %}
+
+The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that
+will be displayed if the value has not changed::
+
+        {% for match in matches %}
+            <div style="background-color:
+                {% ifchanged match.ballot_id %}
+                    {% cycle "red" "blue" %}
+                {% else %}
+                    grey
+                {% endifchanged %}
+            ">{{ match }}</div>
+        {% endfor %}
+
+.. templatetag:: ifequal
+
+ifequal
+~~~~~~~
+
+Output the contents of the block if the two arguments equal each other.
+
+Example::
+
+    {% ifequal user.id comment.user_id %}
+        ...
+    {% endifequal %}
+
+As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.
+
+The arguments can be hard-coded strings, so the following is valid::
+
+    {% ifequal user.username "adrian" %}
+        ...
+    {% endifequal %}
+
+It is only possible to compare an argument to template variables or strings.
+You cannot check for equality with Python objects such as ``True`` or
+``False``.  If you need to test if something is true or false, use the ``if``
+tag instead.
+
+.. versionadded:: 1.2
+   An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator.
+
+.. templatetag:: ifnotequal
+
+ifnotequal
+~~~~~~~~~~
+
+Just like ``ifequal``, except it tests that the two arguments are not equal.
+
+.. versionadded:: 1.2
+   An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator.
+
+.. templatetag:: include
+
+include
+~~~~~~~
+
+Loads a template and renders it with the current context. This is a way of
+"including" other templates within a template.
+
+The template name can either be a variable or a hard-coded (quoted) string,
+in either single or double quotes.
+
+This example includes the contents of the template ``"foo/bar.html"``::
+
+    {% include "foo/bar.html" %}
+
+This example includes the contents of the template whose name is contained in
+the variable ``template_name``::
+
+    {% include template_name %}
+
+An included template is rendered with the context of the template that's
+including it. This example produces the output ``"Hello, John"``:
+
+    * Context: variable ``person`` is set to ``"john"``.
+    * Template::
+
+        {% include "name_snippet.html" %}
+
+    * The ``name_snippet.html`` template::
+
+        Hello, {{ person }}
+
+See also: ``{% ssi %}``.
+
+.. note::
+    The :ttag:`include` tag should be considered as an implementation of
+    "render this subtemplate and include the HTML", not as "parse this
+    subtemplate and include its contents as if it were part of the parent".
+    This means that there is no shared state between included templates --
+    each include is a completely independent rendering process.
+
+.. templatetag:: load
+
+load
+~~~~
+
+Load a custom template tag set.
+
+See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information.
+
+.. templatetag:: now
+
+now
+~~~
+
+Display the current date and/or time, according to the given string.
+
+Given format can be one of the predefined ones ``DATE_FORMAT``,
+``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``,
+or a custom format, same as the :tfilter:`date` filter. Note that predefined
+formats may vary depending on the current locale.
+
+Example::
+
+    It is {% now "jS F Y H:i" %}
+
+Note that you can backslash-escape a format string if you want to use the
+"raw" value. In this example, "f" is backslash-escaped, because otherwise
+"f" is a format string that displays the time. The "o" doesn't need to be
+escaped, because it's not a format character::
+
+    It is the {% now "jS o\f F" %}
+
+This would display as "It is the 4th of September".
+
+.. templatetag:: regroup
+
+regroup
+~~~~~~~
+
+Regroup a list of alike objects by a common attribute.
+
+This complex tag is best illustrated by use of an example: say that ``people``
+is a list of people represented by dictionaries with ``first_name``,
+``last_name``, and ``gender`` keys:
+
+.. code-block:: python
+
+    people = [
+        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
+        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
+        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
+        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
+        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
+    ]
+
+...and you'd like to display a hierarchical list that is ordered by gender,
+like this:
+
+    * Male:
+        * George Bush
+        * Bill Clinton
+    * Female:
+        * Margaret Thatcher
+        * Condoleezza Rice
+    * Unknown:
+        * Pat Smith
+
+You can use the ``{% regroup %}`` tag to group the list of people by gender.
+The following snippet of template code would accomplish this::
+
+    {% regroup people by gender as gender_list %}
+
+    <ul>
+    {% for gender in gender_list %}
+        <li>{{ gender.grouper }}
+        <ul>
+            {% for item in gender.list %}
+            <li>{{ item.first_name }} {{ item.last_name }}</li>
+            {% endfor %}
+        </ul>
+        </li>
+    {% endfor %}
+    </ul>
+
+Let's walk through this example. ``{% regroup %}`` takes three arguments: the
+list you want to regroup, the attribute to group by, and the name of the
+resulting list. Here, we're regrouping the ``people`` list by the ``gender``
+attribute and calling the result ``gender_list``.
+
+``{% regroup %}`` produces a list (in this case, ``gender_list``) of
+**group objects**. Each group object has two attributes:
+
+    * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
+      "Female").
+    * ``list`` -- a list of all items in this group (e.g., a list of all people
+      with gender='Male').
+
+Note that ``{% regroup %}`` does not order its input! Our example relies on
+the fact that the ``people`` list was ordered by ``gender`` in the first place.
+If the ``people`` list did *not* order its members by ``gender``, the regrouping
+would naively display more than one group for a single gender. For example,
+say the ``people`` list was set to this (note that the males are not grouped
+together):
+
+.. code-block:: python
+
+    people = [
+        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
+        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
+        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
+        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
+        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
+    ]
+
+With this input for ``people``, the example ``{% regroup %}`` template code
+above would result in the following output:
+
+    * Male:
+        * Bill Clinton
+    * Unknown:
+        * Pat Smith
+    * Female:
+        * Margaret Thatcher
+    * Male:
+        * George Bush
+    * Female:
+        * Condoleezza Rice
+
+The easiest solution to this gotcha is to make sure in your view code that the
+data is ordered according to how you want to display it.
+
+Another solution is to sort the data in the template using the ``dictsort``
+filter, if your data is in a list of dictionaries::
+
+    {% regroup people|dictsort:"gender" by gender as gender_list %}
+
+.. templatetag:: spaceless
+
+spaceless
+~~~~~~~~~
+
+Removes whitespace between HTML tags. This includes tab
+characters and newlines.
+
+Example usage::
+
+    {% spaceless %}
+        <p>
+            <a href="foo/">Foo</a>
+        </p>
+    {% endspaceless %}
+
+This example would return this HTML::
+
+    <p><a href="foo/">Foo</a></p>
+
+Only space between *tags* is removed -- not space between tags and text. In
+this example, the space around ``Hello`` won't be stripped::
+
+    {% spaceless %}
+        <strong>
+            Hello
+        </strong>
+    {% endspaceless %}
+
+.. templatetag:: ssi
+
+ssi
+~~~
+
+Output the contents of a given file into the page.
+
+Like a simple "include" tag, ``{% ssi %}`` includes the contents of another
+file -- which must be specified using an absolute path -- in the current
+page::
+
+    {% ssi /home/html/ljworld.com/includes/right_generic.html %}
+
+If the optional "parsed" parameter is given, the contents of the included
+file are evaluated as template code, within the current context::
+
+    {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
+
+Note that if you use ``{% ssi %}``, you'll need to define
+:setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure.
+
+See also: ``{% include %}``.
+
+.. templatetag:: templatetag
+
+templatetag
+~~~~~~~~~~~
+
+Output one of the syntax characters used to compose template tags.
+
+Since the template system has no concept of "escaping", to display one of the
+bits used in template tags, you must use the ``{% templatetag %}`` tag.
+
+The argument tells which template bit to output:
+
+    ==================  =======
+    Argument            Outputs
+    ==================  =======
+    ``openblock``       ``{%``
+    ``closeblock``      ``%}``
+    ``openvariable``    ``{{``
+    ``closevariable``   ``}}``
+    ``openbrace``       ``{``
+    ``closebrace``      ``}``
+    ``opencomment``     ``{#``
+    ``closecomment``    ``#}``
+    ==================  =======
+
+.. templatetag:: url
+
+url
+~~~
+
+Returns an absolute path reference (a URL without the domain name) matching a
+given view function and optional parameters. This is a way to output links
+without violating the DRY principle by having to hard-code URLs in your
+templates::
+
+    {% url path.to.some_view v1 v2 %}
+
+The first argument is a path to a view function in the format
+``package.package.module.function``. Additional arguments are optional and
+should be space-separated values that will be used as arguments in the URL.
+The example above shows passing positional arguments. Alternatively you may
+use keyword syntax::
+
+    {% url path.to.some_view arg1=v1 arg2=v2 %}
+
+Do not mix both positional and keyword syntax in a single call. All arguments
+required by the URLconf should be present.
+
+For example, suppose you have a view, ``app_views.client``, whose URLconf
+takes a client ID (here, ``client()`` is a method inside the views file
+``app_views.py``). The URLconf line might look like this:
+
+.. code-block:: python
+
+    ('^client/(\d+)/$', 'app_views.client')
+
+If this app's URLconf is included into the project's URLconf under a path
+such as this:
+
+.. code-block:: python
+
+    ('^clients/', include('project_name.app_name.urls'))
+
+...then, in a template, you can create a link to this view like this::
+
+    {% url app_views.client client.id %}
+
+The template tag will output the string ``/clients/client/123/``.
+
+.. versionadded:: 1.0
+
+If you're using :ref:`named URL patterns <naming-url-patterns>`, you can
+refer to the name of the pattern in the ``url`` tag instead of using the
+path to the view.
+
+Note that if the URL you're reversing doesn't exist, you'll get an
+:exc:`NoReverseMatch` exception raised, which will cause your site to display an
+error page.
+
+.. versionadded:: 1.0
+
+If you'd like to retrieve a URL without displaying it, you can use a slightly
+different call::
+
+
+    {% url path.to.view arg arg2 as the_url %}
+
+    <a href="{{ the_url }}">I'm linking to {{ the_url }}</a>
+
+This ``{% url ... as var %}`` syntax will *not* cause an error if the view is
+missing. In practice you'll use this to link to views that are optional::
+
+    {% url path.to.view as the_url %}
+    {% if the_url %}
+      <a href="{{ the_url }}">Link to optional stuff</a>
+    {% endif %}
+
+.. versionadded:: 1.1
+
+If you'd like to retrieve a namespaced URL, specify the fully qualified name::
+
+    {% url myapp:view-name %}
+
+This will follow the normal :ref:`namespaced URL resolution strategy
+<topics-http-reversing-url-namespaces>`, including using any hints provided
+by the context as to the current application.
+
+.. versionchanged:: 1.2
+
+For backwards compatibility, the ``{% url %}`` tag also supports the
+use of commas to separate arguments. You shouldn't use this in any new
+projects, but for the sake of the people who are still using it,
+here's what it looks like::
+
+    {% url path.to.view arg,arg2 %}
+    {% url path.to.view arg, arg2 %}
+
+This syntax doesn't support the use of literal commas, or or equals
+signs. Did we mention you shouldn't use this syntax in any new
+projects?
+
+.. templatetag:: widthratio
+
+widthratio
+~~~~~~~~~~
+
+For creating bar charts and such, this tag calculates the ratio of a given value
+to a maximum value, and then applies that ratio to a constant.
+
+For example::
+
+    <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />
+
+Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the
+above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
+which is rounded up to 88).
+
+.. templatetag:: with
+
+with
+~~~~
+
+.. versionadded:: 1.0
+
+Caches a complex variable under a simpler name. This is useful when accessing
+an "expensive" method (e.g., one that hits the database) multiple times.
+
+For example::
+
+    {% with business.employees.count as total %}
+        {{ total }} employee{{ total|pluralize }}
+    {% endwith %}
+
+The populated variable (in the example above, ``total``) is only available
+between the ``{% with %}`` and ``{% endwith %}`` tags.
+
+.. _ref-templates-builtins-filters:
+
+Built-in filter reference
+-------------------------
+
+.. templatefilter:: add
+
+add
+~~~
+
+Adds the argument to the value.
+
+For example::
+
+    {{ value|add:"2" }}
+
+If ``value`` is ``4``, then the output will be ``6``.
+
+.. versionchanged:: 1.2
+   The following behavior didn't exist in previous Django versions.
+
+This filter will first try to coerce both values to integers. If this fails,
+it'll attempt to add the values together anyway. This will work on some data
+types (strings, list, etc.) and fail on others. If it fails, the result will
+be an empty string.
+
+For example, if we have::
+
+    {{ first|add:second }}
+
+and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the
+output will be ``[1, 2, 3, 4, 5, 6]``.
+
+.. warning::
+
+    Strings that can be coerced to integers will be **summed**, not
+    concatenated, as in the first example above.
+
+.. templatefilter:: addslashes
+
+addslashes
+~~~~~~~~~~
+
+Adds slashes before quotes. Useful for escaping strings in CSV, for example.
+
+For example::
+
+    {{ value|addslashes }}
+
+If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``.
+
+.. templatefilter:: capfirst
+
+capfirst
+~~~~~~~~
+
+Capitalizes the first character of the value.
+
+For example::
+
+    {{ value|capfirst }}
+
+If ``value`` is ``"django"``, the output will be ``"Django"``.
+
+.. templatefilter:: center
+
+center
+~~~~~~
+
+Centers the value in a field of a given width.
+
+For example::
+
+    "{{ value|center:"15" }}"
+
+If ``value`` is ``"Django"``, the output will be ``"     Django    "``.
+
+.. templatefilter:: cut
+
+cut
+~~~
+
+Removes all values of arg from the given string.
+
+For example::
+
+    {{ value|cut:" "}}
+
+If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``.
+
+.. templatefilter:: date
+
+date
+~~~~
+
+Formats a date according to the given format.
+
+Uses the same format as PHP's ``date()`` function (http://php.net/date)
+with some custom extensions.
+
+Available format strings:
+
+    ================  ========================================  =====================
+    Format character  Description                               Example output
+    ================  ========================================  =====================
+    a                 ``'a.m.'`` or ``'p.m.'`` (Note that       ``'a.m.'``
+                      this is slightly different than PHP's
+                      output, because this includes periods
+                      to match Associated Press style.)
+    A                 ``'AM'`` or ``'PM'``.                     ``'AM'``
+    b                 Month, textual, 3 letters, lowercase.     ``'jan'``
+    B                 Not implemented.
+    c                 ISO 8601 Format.                          ``2008-01-02T10:30:00.000123``
+    d                 Day of the month, 2 digits with           ``'01'`` to ``'31'``
+                      leading zeros.
+    D                 Day of the week, textual, 3 letters.      ``'Fri'``
+    f                 Time, in 12-hour hours and minutes,       ``'1'``, ``'1:30'``
+                      with minutes left off if they're zero.
+                      Proprietary extension.
+    F                 Month, textual, long.                     ``'January'``
+    g                 Hour, 12-hour format without leading      ``'1'`` to ``'12'``
+                      zeros.
+    G                 Hour, 24-hour format without leading      ``'0'`` to ``'23'``
+                      zeros.
+    h                 Hour, 12-hour format.                     ``'01'`` to ``'12'``
+    H                 Hour, 24-hour format.                     ``'00'`` to ``'23'``
+    i                 Minutes.                                  ``'00'`` to ``'59'``
+    I                 Not implemented.
+    j                 Day of the month without leading          ``'1'`` to ``'31'``
+                      zeros.
+    l                 Day of the week, textual, long.           ``'Friday'``
+    L                 Boolean for whether it's a leap year.     ``True`` or ``False``
+    m                 Month, 2 digits with leading zeros.       ``'01'`` to ``'12'``
+    M                 Month, textual, 3 letters.                ``'Jan'``
+    n                 Month without leading zeros.              ``'1'`` to ``'12'``
+    N                 Month abbreviation in Associated Press    ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``
+                      style. Proprietary extension.
+    O                 Difference to Greenwich time in hours.    ``'+0200'``
+    P                 Time, in 12-hour hours, minutes and       ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'``
+                      'a.m.'/'p.m.', with minutes left off
+                      if they're zero and the special-case
+                      strings 'midnight' and 'noon' if
+                      appropriate. Proprietary extension.
+    r                 RFC 2822 formatted date.                  ``'Thu, 21 Dec 2000 16:01:07 +0200'``
+    s                 Seconds, 2 digits with leading zeros.     ``'00'`` to ``'59'``
+    S                 English ordinal suffix for day of the     ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
+                      month, 2 characters.
+    t                 Number of days in the given month.        ``28`` to ``31``
+    T                 Time zone of this machine.                ``'EST'``, ``'MDT'``
+    u                 Microseconds.                             ``0`` to ``999999``
+    U                 Seconds since the Unix Epoch
+                      (January 1 1970 00:00:00 UTC).
+    w                 Day of the week, digits without           ``'0'`` (Sunday) to ``'6'`` (Saturday)
+                      leading zeros.
+    W                 ISO-8601 week number of year, with        ``1``, ``53``
+                      weeks starting on Monday.
+    y                 Year, 2 digits.                           ``'99'``
+    Y                 Year, 4 digits.                           ``'1999'``
+    z                 Day of the year.                          ``0`` to ``365``
+    Z                 Time zone offset in seconds. The          ``-43200`` to ``43200``
+                      offset for timezones west of UTC is
+                      always negative, and for those east of
+                      UTC is always positive.
+    ================  ========================================  =====================
+
+.. versionadded:: 1.2
+
+The ``c`` and ``u`` format specification characters were added in Django 1.2.
+
+For example::
+
+    {{ value|date:"D d M Y" }}
+
+If ``value`` is a ``datetime`` object (e.g., the result of
+``datetime.datetime.now()``), the output will be the string
+``'Wed 09 Jan 2008'``.
+
+The format passed can be one of the predefined ones ``DATE_FORMAT``,
+``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, or a
+custom format that uses the format specifiers shown in the table above. Note
+that predefined formats may vary depending on the current locale.
+
+Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is,
+for example, ``"es"``, then for::
+
+    {{ value|date:"SHORT_DATE_FORMAT" }}
+
+the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"``
+format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``).
+
+When used without a format string::
+
+    {{ value|date }}
+
+...the formatting string defined in the :setting:`DATE_FORMAT` setting will be
+used, without applying any localization.
+
+.. versionchanged:: 1.2
+    Predefined formats can now be influenced by the current locale.
+
+.. templatefilter:: default
+
+default
+~~~~~~~
+
+If value evaluates to ``False``, use given default. Otherwise, use the value.
+
+For example::
+
+    {{ value|default:"nothing" }}
+
+If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
+
+.. templatefilter:: default_if_none
+
+default_if_none
+~~~~~~~~~~~~~~~
+
+If (and only if) value is ``None``, use given default. Otherwise, use the
+value.
+
+Note that if an empty string is given, the default value will *not* be used.
+Use the ``default`` filter if you want to fallback for empty strings.
+
+For example::
+
+    {{ value|default_if_none:"nothing" }}
+
+If ``value`` is ``None``, the output will be the string ``"nothing"``.
+
+.. templatefilter:: dictsort
+
+dictsort
+~~~~~~~~
+
+Takes a list of dictionaries and returns that list sorted by the key given in
+the argument.
+
+For example::
+
+    {{ value|dictsort:"name" }}
+
+If ``value`` is:
+
+.. code-block:: python
+
+    [
+        {'name': 'zed', 'age': 19},
+        {'name': 'amy', 'age': 22},
+        {'name': 'joe', 'age': 31},
+    ]
+
+then the output would be:
+
+.. code-block:: python
+
+    [
+        {'name': 'amy', 'age': 22},
+        {'name': 'joe', 'age': 31},
+        {'name': 'zed', 'age': 19},
+    ]
+
+.. templatefilter:: dictsortreversed
+
+dictsortreversed
+~~~~~~~~~~~~~~~~
+
+Takes a list of dictionaries and returns that list sorted in reverse order by
+the key given in the argument. This works exactly the same as the above filter,
+but the returned value will be in reverse order.
+
+.. templatefilter:: divisibleby
+
+divisibleby
+~~~~~~~~~~~
+
+Returns ``True`` if the value is divisible by the argument.
+
+For example::
+
+    {{ value|divisibleby:"3" }}
+
+If ``value`` is ``21``, the output would be ``True``.
+
+.. templatefilter:: escape
+
+escape
+~~~~~~
+
+Escapes a string's HTML. Specifically, it makes these replacements:
+
+    * ``<`` is converted to ``&lt;``
+    * ``>`` is converted to ``&gt;``
+    * ``'`` (single quote) is converted to ``&#39;``
+    * ``"`` (double quote) is converted to ``&quot;``
+    * ``&`` is converted to ``&amp;``
+
+The escaping is only applied when the string is output, so it does not matter
+where in a chained sequence of filters you put ``escape``: it will always be
+applied as though it were the last filter. If you want escaping to be applied
+immediately, use the ``force_escape`` filter.
+
+Applying ``escape`` to a variable that would normally have auto-escaping
+applied to the result will only result in one round of escaping being done. So
+it is safe to use this function even in auto-escaping environments. If you want
+multiple escaping passes to be applied, use the ``force_escape`` filter.
+
+.. versionchanged:: 1.0
+    Due to auto-escaping, the behavior of this filter has changed slightly.
+    The replacements are only made once, after
+    all other filters are applied -- including filters before and after it.
+
+.. templatefilter:: escapejs
+
+escapejs
+~~~~~~~~
+
+.. versionadded:: 1.0
+
+Escapes characters for use in JavaScript strings. This does *not* make the
+string safe for use in HTML, but does protect you from syntax errors when using
+templates to generate JavaScript/JSON.
+
+For example::
+
+    {{ value|escapejs }}
+
+If ``value`` is ``"testing\r\njavascript \'string" <b>escaping</b>"``,
+the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"``.
+
+.. templatefilter:: filesizeformat
+
+filesizeformat
+~~~~~~~~~~~~~~
+
+Format the value like a 'human-readable' file size (i.e. ``'13 KB'``,
+``'4.1 MB'``, ``'102 bytes'``, etc).
+
+For example::
+
+    {{ value|filesizeformat }}
+
+If ``value`` is 123456789, the output would be ``117.7 MB``.
+
+.. templatefilter:: first
+
+first
+~~~~~
+
+Returns the first item in a list.
+
+For example::
+
+    {{ value|first }}
+
+If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``.
+
+.. templatefilter:: fix_ampersands
+
+fix_ampersands
+~~~~~~~~~~~~~~
+
+.. versionchanged:: 1.0
+    This is rarely useful as ampersands are now automatically escaped. See escape_ for more information.
+
+Replaces ampersands with ``&amp;`` entities.
+
+For example::
+
+    {{ value|fix_ampersands }}
+
+If ``value`` is ``Tom & Jerry``, the output will be ``Tom &amp; Jerry``.
+
+.. templatefilter:: floatformat
+
+floatformat
+~~~~~~~~~~~
+
+When used without an argument, rounds a floating-point number to one decimal
+place -- but only if there's a decimal part to be displayed. For example:
+
+============  ===========================  ========
+``value``     Template                     Output
+============  ===========================  ========
+``34.23234``  ``{{ value|floatformat }}``  ``34.2``
+``34.00000``  ``{{ value|floatformat }}``  ``34``
+``34.26000``  ``{{ value|floatformat }}``  ``34.3``
+============  ===========================  ========
+
+If used with a numeric integer argument, ``floatformat`` rounds a number to
+that many decimal places. For example:
+
+============  =============================  ==========
+``value``     Template                       Output
+============  =============================  ==========
+``34.23234``  ``{{ value|floatformat:3 }}``  ``34.232``
+``34.00000``  ``{{ value|floatformat:3 }}``  ``34.000``
+``34.26000``  ``{{ value|floatformat:3 }}``  ``34.260``
+============  =============================  ==========
+
+If the argument passed to ``floatformat`` is negative, it will round a number
+to that many decimal places -- but only if there's a decimal part to be
+displayed. For example:
+
+============  ================================  ==========
+``value``     Template                          Output
+============  ================================  ==========
+``34.23234``  ``{{ value|floatformat:"-3" }}``  ``34.232``
+``34.00000``  ``{{ value|floatformat:"-3" }}``  ``34``
+``34.26000``  ``{{ value|floatformat:"-3" }}``  ``34.260``
+============  ================================  ==========
+
+Using ``floatformat`` with no argument is equivalent to using ``floatformat``
+with an argument of ``-1``.
+
+.. templatefilter:: force_escape
+
+force_escape
+~~~~~~~~~~~~
+
+.. versionadded:: 1.0
+
+Applies HTML escaping to a string (see the ``escape`` filter for details).
+This filter is applied *immediately* and returns a new, escaped string. This
+is useful in the rare cases where you need multiple escaping or want to apply
+other filters to the escaped results. Normally, you want to use the ``escape``
+filter.
+
+.. templatefilter:: get_digit
+
+get_digit
+~~~~~~~~~
+
+Given a whole number, returns the requested digit, where 1 is the right-most
+digit, 2 is the second-right-most digit, etc. Returns the original value for
+invalid input (if input or argument is not an integer, or if argument is less
+than 1). Otherwise, output is always an integer.
+
+For example::
+
+    {{ value|get_digit:"2" }}
+
+If ``value`` is ``123456789``, the output will be ``8``.
+
+.. templatefilter:: iriencode
+
+iriencode
+~~~~~~~~~
+
+Converts an IRI (Internationalized Resource Identifier) to a string that is
+suitable for including in a URL. This is necessary if you're trying to use
+strings containing non-ASCII characters in a URL.
+
+It's safe to use this filter on a string that has already gone through the
+``urlencode`` filter.
+
+For example::
+
+    {{ value|iriencode }}
+
+If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
+
+.. templatefilter:: join
+
+join
+~~~~
+
+Joins a list with a string, like Python's ``str.join(list)``
+
+For example::
+
+    {{ value|join:" // " }}
+
+If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string
+``"a // b // c"``.
+
+.. templatefilter:: last
+
+last
+~~~~
+
+.. versionadded:: 1.0
+
+Returns the last item in a list.
+
+For example::
+
+    {{ value|last }}
+
+If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string
+``"d"``.
+
+.. templatefilter:: length
+
+length
+~~~~~~
+
+Returns the length of the value. This works for both strings and lists.
+
+For example::
+
+    {{ value|length }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``.
+
+.. templatefilter:: length_is
+
+length_is
+~~~~~~~~~
+
+Returns ``True`` if the value's length is the argument, or ``False`` otherwise.
+
+For example::
+
+    {{ value|length_is:"4" }}
+
+If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``.
+
+.. templatefilter:: linebreaks
+
+linebreaks
+~~~~~~~~~~
+
+Replaces line breaks in plain text with appropriate HTML; a single
+newline becomes an HTML line break (``<br />``) and a new line
+followed by a blank line becomes a paragraph break (``</p>``).
+
+For example::
+
+    {{ value|linebreaks }}
+
+If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joel<br />is a
+slug</p>``.
+
+.. templatefilter:: linebreaksbr
+
+linebreaksbr
+~~~~~~~~~~~~
+
+Converts all newlines in a piece of plain text to HTML line breaks
+(``<br />``).
+
+For example::
+
+    {{ value|linebreaksbr }}
+
+If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a
+slug``.
+
+.. templatefilter:: linenumbers
+
+linenumbers
+~~~~~~~~~~~
+
+Displays text with line numbers.
+
+For example::
+
+    {{ value|linenumbers }}
+
+If ``value`` is::
+
+    one
+    two
+    three
+
+the output will be::
+
+    1. one
+    2. two
+    3. three
+
+.. templatefilter:: ljust
+
+ljust
+~~~~~
+
+Left-aligns the value in a field of a given width.
+
+**Argument:** field size
+
+For example::
+
+    "{{ value|ljust:"10" }}"
+
+If ``value`` is ``Django``, the output will be ``"Django    "``.
+
+.. templatefilter:: lower
+
+lower
+~~~~~
+
+Converts a string into all lowercase.
+
+For example::
+
+    {{ value|lower }}
+
+If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``.
+
+.. templatefilter:: make_list
+
+make_list
+~~~~~~~~~
+
+Returns the value turned into a list. For an integer, it's a list of
+digits. For a string, it's a list of characters.
+
+For example::
+
+    {{ value|make_list }}
+
+If ``value`` is the string ``"Joel"``, the output would be the list
+``[u'J', u'o', u'e', u'l']``. If ``value`` is ``123``, the output will be the
+list ``[1, 2, 3]``.
+
+.. templatefilter:: phone2numeric
+
+phone2numeric
+~~~~~~~~~~~~~
+
+Converts a phone number (possibly containing letters) to its numerical
+equivalent.
+
+The input doesn't have to be a valid phone number. This will happily convert
+any string.
+
+For example::
+
+    {{ value|phone2numeric }}
+
+If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
+
+.. templatefilter:: pluralize
+
+pluralize
+~~~~~~~~~
+
+Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``.
+
+Example::
+
+    You have {{ num_messages }} message{{ num_messages|pluralize }}.
+
+If ``num_messages`` is ``1``, the output will be ``You have 1 message.``
+If ``num_messages`` is ``2``  the output will be ``You have 2 messages.``
+
+For words that require a suffix other than ``'s'``, you can provide an alternate
+suffix as a parameter to the filter.
+
+Example::
+
+    You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}.
+
+For words that don't pluralize by simple suffix, you can specify both a
+singular and plural suffix, separated by a comma.
+
+Example::
+
+    You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}.
+
+.. templatefilter:: pprint
+
+pprint
+~~~~~~
+
+A wrapper around `pprint.pprint`__ -- for debugging, really.
+
+__ http://docs.python.org/library/pprint.html
+
+.. templatefilter:: random
+
+random
+~~~~~~
+
+Returns a random item from the given list.
+
+For example::
+
+    {{ value|random }}
+
+If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
+
+.. templatefilter:: removetags
+
+removetags
+~~~~~~~~~~
+
+Removes a space-separated list of [X]HTML tags from the output.
+
+For example::
+
+    {{ value|removetags:"b span"|safe }}
+
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the
+output will be ``"Joel <button>is</button> a slug"``.
+
+Note that this filter is case-sensitive.
+
+If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the
+output will be ``"<B>Joel</B> <button>is</button> a slug"``.
+
+.. templatefilter:: rjust
+
+rjust
+~~~~~
+
+Right-aligns the value in a field of a given width.
+
+**Argument:** field size
+
+For example::
+
+    "{{ value|rjust:"10" }}"
+
+If ``value`` is ``Django``, the output will be ``"    Django"``.
+
+.. templatefilter:: safe
+
+safe
+~~~~
+
+Marks a string as not requiring further HTML escaping prior to output. When
+autoescaping is off, this filter has no effect.
+
+.. note::
+
+    If you are chaining filters, a filter applied after ``safe`` can
+    make the contents unsafe again. For example, the following code
+    prints the variable as is, unescaped:
+
+    .. code-block:: html+django
+
+        {{ var|safe|escape }}
+
+.. templatefilter:: safeseq
+
+safeseq
+~~~~~~~
+
+Applies the :tfilter:`safe` filter to each element of a sequence.  Useful in
+conjunction with other filters that operate on sequences, such as
+:tfilter:`join`.  For example::
+
+    {{ some_list|safeseq|join:", " }}
+
+You couldn't use the :tfilter:`safe` filter directly in this case, as it would
+first convert the variable into a string, rather than working with the
+individual elements of the sequence.
+
+.. templatefilter:: slice
+
+slice
+~~~~~
+
+Returns a slice of the list.
+
+Uses the same syntax as Python's list slicing. See
+http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
+for an introduction.
+
+Example::
+
+    {{ some_list|slice:":2" }}
+
+If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``.
+
+.. templatefilter:: slugify
+
+slugify
+~~~~~~~
+
+Converts to lowercase, removes non-word characters (alphanumerics and
+underscores) and converts spaces to hyphens. Also strips leading and trailing
+whitespace.
+
+For example::
+
+    {{ value|slugify }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
+
+.. templatefilter:: stringformat
+
+stringformat
+~~~~~~~~~~~~
+
+Formats the variable according to the argument, a string formatting specifier.
+This specifier uses Python string formatting syntax, with the exception that
+the leading "%" is dropped.
+
+See http://docs.python.org/library/stdtypes.html#string-formatting-operations
+for documentation of Python string formatting
+
+For example::
+
+    {{ value|stringformat:"s" }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``.
+
+.. templatefilter:: striptags
+
+striptags
+~~~~~~~~~
+
+Strips all [X]HTML tags.
+
+For example::
+
+    {{ value|striptags }}
+
+If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the
+output will be ``"Joel is a slug"``.
+
+.. templatefilter:: time
+
+time
+~~~~
+
+Formats a time according to the given format.
+
+Given format can be the predefined one ``TIME_FORMAT``, or a custom format,
+same as the :tfilter:`date` filter. Note that the predefined format is locale-
+dependant.
+
+The time filter will only accept parameters in the format string that relate
+to the time of day, not the date (for obvious reasons). If you need to
+format a date, use the :tfilter:`date` filter.
+
+For example::
+
+    {{ value|time:"H:i" }}
+
+If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be
+the string ``"01:23"``.
+
+Another example:
+
+Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is,
+for example, ``"de"``, then for::
+
+    {{ value|time:"TIME_FORMAT" }}
+
+the output will be the string ``"01:23:00"`` (The ``"TIME_FORMAT"`` format
+specifier for the ``de`` locale as shipped with Django is ``"H:i:s"``).
+
+When used without a format string::
+
+    {{ value|time }}
+
+...the formatting string defined in the :setting:`TIME_FORMAT` setting will be
+used, without applying any localization.
+
+.. versionchanged:: 1.2
+    Predefined formats can now be influenced by the current locale.
+
+.. templatefilter:: timesince
+
+timesince
+~~~~~~~~~
+
+Formats a date as the time since that date (e.g., "4 days, 6 hours").
+
+Takes an optional argument that is a variable containing the date to use as
+the comparison point (without the argument, the comparison point is *now*).
+For example, if ``blog_date`` is a date instance representing midnight on 1
+June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006,
+then ``{{ blog_date|timesince:comment_date }}`` would return "8 hours".
+
+Comparing offset-naive and offset-aware datetimes will return an empty string.
+
+Minutes is the smallest unit used, and "0 minutes" will be returned for any
+date that is in the future relative to the comparison point.
+
+.. templatefilter:: timeuntil
+
+timeuntil
+~~~~~~~~~
+
+Similar to ``timesince``, except that it measures the time from now until the
+given date or datetime. For example, if today is 1 June 2006 and
+``conference_date`` is a date instance holding 29 June 2006, then
+``{{ conference_date|timeuntil }}`` will return "4 weeks".
+
+Takes an optional argument that is a variable containing the date to use as
+the comparison point (instead of *now*). If ``from_date`` contains 22 June
+2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week".
+
+Comparing offset-naive and offset-aware datetimes will return an empty string.
+
+Minutes is the smallest unit used, and "0 minutes" will be returned for any
+date that is in the past relative to the comparison point.
+
+.. templatefilter:: title
+
+title
+~~~~~
+
+Converts a string into titlecase.
+
+For example::
+
+    {{ value|title }}
+
+If ``value`` is ``"my first post"``, the output will be ``"My First Post"``.
+
+.. templatefilter:: truncatewords
+
+truncatewords
+~~~~~~~~~~~~~
+
+Truncates a string after a certain number of words.
+
+**Argument:** Number of words to truncate after
+
+For example::
+
+    {{ value|truncatewords:2 }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``.
+
+Newlines within the string will be removed.
+
+.. templatefilter:: truncatewords_html
+
+truncatewords_html
+~~~~~~~~~~~~~~~~~~
+
+Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags
+that are opened in the string and not closed before the truncation point, are
+closed immediately after the truncation.
+
+This is less efficient than ``truncatewords``, so should only be used when it
+is being passed HTML text.
+
+For example::
+
+    {{ value|truncatewords_html:2 }}
+
+If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be
+``"<p>Joel is ...</p>"``.
+
+Newlines in the HTML content will be preserved.
+
+.. templatefilter:: unordered_list
+
+unordered_list
+~~~~~~~~~~~~~~
+
+Recursively takes a self-nested list and returns an HTML unordered list --
+WITHOUT opening and closing <ul> tags.
+
+.. versionchanged:: 1.0
+   The format accepted by ``unordered_list`` has changed to be easier to understand.
+
+The list is assumed to be in the proper format. For example, if ``var`` contains
+``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
+``{{ var|unordered_list }}`` would return::
+
+    <li>States
+    <ul>
+            <li>Kansas
+            <ul>
+                    <li>Lawrence</li>
+                    <li>Topeka</li>
+            </ul>
+            </li>
+            <li>Illinois</li>
+    </ul>
+    </li>
+
+Note: the previous more restrictive and verbose format is still supported:
+``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
+
+.. templatefilter:: upper
+
+upper
+~~~~~
+
+Converts a string into all uppercase.
+
+For example::
+
+    {{ value|upper }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``.
+
+.. templatefilter:: urlencode
+
+urlencode
+~~~~~~~~~
+
+Escapes a value for use in a URL.
+
+For example::
+
+    {{ value|urlencode }}
+
+If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be
+``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``.
+
+.. templatefilter:: urlize
+
+urlize
+~~~~~~
+
+Converts URLs in plain text into clickable links.
+
+Note that if ``urlize`` is applied to text that already contains HTML markup,
+things won't work as expected. Apply this filter only to *plain* text.
+
+For example::
+
+    {{ value|urlize }}
+
+If ``value`` is ``"Check out www.djangoproject.com"``, the output will be
+``"Check out <a
+href="http://www.djangoproject.com">www.djangoproject.com</a>"``.
+
+.. templatefilter:: urlizetrunc
+
+urlizetrunc
+~~~~~~~~~~~
+
+Converts URLs into clickable links, truncating URLs longer than the given
+character limit.
+
+As with urlize_, this filter should only be applied to *plain* text.
+
+**Argument:** Length to truncate URLs to
+
+For example::
+
+    {{ value|urlizetrunc:15 }}
+
+If ``value`` is ``"Check out www.djangoproject.com"``, the output would be
+``'Check out <a
+href="http://www.djangoproject.com">www.djangopr...</a>'``.
+
+.. templatefilter:: wordcount
+
+wordcount
+~~~~~~~~~
+
+Returns the number of words.
+
+For example::
+
+    {{ value|wordcount }}
+
+If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
+
+.. templatefilter:: wordwrap
+
+wordwrap
+~~~~~~~~
+
+Wraps words at specified line length.
+
+**Argument:** number of characters at which to wrap the text
+
+For example::
+
+    {{ value|wordwrap:5 }}
+
+If ``value`` is ``Joel is a slug``, the output would be::
+
+    Joel
+    is a
+    slug
+
+.. templatefilter:: yesno
+
+yesno
+~~~~~
+
+Given a string mapping values for true, false and (optionally) None,
+returns one of those strings according to the value:
+
+For example::
+
+    {{ value|yesno:"yeah,no,maybe" }}
+
+==========  ======================  ==================================
+Value       Argument                Outputs
+==========  ======================  ==================================
+``True``    ``"yeah,no,maybe"``     ``yeah``
+``False``   ``"yeah,no,maybe"``     ``no``
+``None``    ``"yeah,no,maybe"``     ``maybe``
+``None``    ``"yeah,no"``           ``"no"`` (converts None to False
+                                    if no mapping for None is given)
+==========  ======================  ==================================
+
+Other tags and filter libraries
+-------------------------------
+
+Django comes with a couple of other template-tag libraries that you have to
+enable explicitly in your ``INSTALLED_APPS`` setting and enable in your
+template with the ``{% load %}`` tag.
+
+django.contrib.humanize
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A set of Django template filters useful for adding a "human touch" to data. See
+:doc:`/ref/contrib/humanize`.
+
+django.contrib.markup
+~~~~~~~~~~~~~~~~~~~~~
+
+A collection of template filters that implement these common markup languages:
+
+    * Textile
+    * Markdown
+    * reST (reStructuredText)
+
+See the :doc:`markup documentation </ref/contrib/markup>`.
+
+django.contrib.webdesign
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A collection of template tags that can be useful while designing a Web site,
+such as a generator of Lorem Ipsum text. See :doc:`/ref/contrib/webdesign`.
+
+i18n
+~~~~
+
+Provides a couple of templatetags that allow specifying translatable text in
+Django templates. It is slightly different from the libraries described
+above because you don't need to add any application to the ``INSTALLED_APPS``
+setting but rather set :setting:`USE_I18N` to True, then loading it with
+``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`.
diff --git a/parts/django/docs/ref/templates/index.txt b/parts/django/docs/ref/templates/index.txt
new file mode 100644
index 0000000..0aa4798
--- /dev/null
+++ b/parts/django/docs/ref/templates/index.txt
@@ -0,0 +1,19 @@
+=========
+Templates
+=========
+
+Django's template engine provides a powerful mini-language for defining the
+user-facing layer of your application, encouraging a clean separation of
+application and presentation logic. Templates can be maintained by anyone with
+an understanding of HTML; no knowledge of Python is required.
+
+.. toctree::
+   :maxdepth: 2
+
+   builtins
+   api
+
+.. seealso::
+
+    For information on writing your own custom tags and filters, see
+    :doc:`/howto/custom-template-tags`.
diff --git a/parts/django/docs/ref/unicode.txt b/parts/django/docs/ref/unicode.txt
new file mode 100644
index 0000000..8e110af
--- /dev/null
+++ b/parts/django/docs/ref/unicode.txt
@@ -0,0 +1,362 @@
+============
+Unicode data
+============
+
+.. versionadded:: 1.0
+
+Django natively supports Unicode data everywhere. Providing your database can
+somehow store the data, you can safely pass around Unicode strings to
+templates, models and the database.
+
+This document tells you what you need to know if you're writing applications
+that use data or templates that are encoded in something other than ASCII.
+
+Creating the database
+=====================
+
+Make sure your database is configured to be able to store arbitrary string
+data. Normally, this means giving it an encoding of UTF-8 or UTF-16. If you use
+a more restrictive encoding -- for example, latin1 (iso8859-1) -- you won't be
+able to store certain characters in the database, and information will be lost.
+
+ * MySQL users, refer to the `MySQL manual`_ (section 9.1.3.2 for MySQL 5.1)
+   for details on how to set or alter the database character set encoding.
+
+ * PostgreSQL users, refer to the `PostgreSQL manual`_ (section 21.2.2 in
+   PostgreSQL 8) for details on creating databases with the correct encoding.
+
+ * SQLite users, there is nothing you need to do. SQLite always uses UTF-8
+   for internal encoding.
+
+.. _MySQL manual: http://dev.mysql.com/doc/refman/5.1/en/charset-database.html
+.. _PostgreSQL manual: http://www.postgresql.org/docs/8.2/static/multibyte.html#AEN24104
+
+All of Django's database backends automatically convert Unicode strings into
+the appropriate encoding for talking to the database. They also automatically
+convert strings retrieved from the database into Python Unicode strings. You
+don't even need to tell Django what encoding your database uses: that is
+handled transparently.
+
+For more, see the section "The database API" below.
+
+General string handling
+=======================
+
+Whenever you use strings with Django -- e.g., in database lookups, template
+rendering or anywhere else -- you have two choices for encoding those strings.
+You can use Unicode strings, or you can use normal strings (sometimes called
+"bytestrings") that are encoded using UTF-8.
+
+.. admonition:: Warning
+
+    A bytestring does not carry any information with it about its encoding.
+    For that reason, we have to make an assumption, and Django assumes that all
+    bytestrings are in UTF-8.
+
+    If you pass a string to Django that has been encoded in some other format,
+    things will go wrong in interesting ways. Usually, Django will raise a
+    ``UnicodeDecodeError`` at some point.
+
+If your code only uses ASCII data, it's safe to use your normal strings,
+passing them around at will, because ASCII is a subset of UTF-8.
+
+Don't be fooled into thinking that if your :setting:`DEFAULT_CHARSET` setting is set
+to something other than ``'utf-8'`` you can use that other encoding in your
+bytestrings! :setting:`DEFAULT_CHARSET` only applies to the strings generated as
+the result of template rendering (and e-mail). Django will always assume UTF-8
+encoding for internal bytestrings. The reason for this is that the
+:setting:`DEFAULT_CHARSET` setting is not actually under your control (if you are the
+application developer). It's under the control of the person installing and
+using your application -- and if that person chooses a different setting, your
+code must still continue to work. Ergo, it cannot rely on that setting.
+
+In most cases when Django is dealing with strings, it will convert them to
+Unicode strings before doing anything else. So, as a general rule, if you pass
+in a bytestring, be prepared to receive a Unicode string back in the result.
+
+Translated strings
+------------------
+
+Aside from Unicode strings and bytestrings, there's a third type of string-like
+object you may encounter when using Django. The framework's
+internationalization features introduce the concept of a "lazy translation" --
+a string that has been marked as translated but whose actual translation result
+isn't determined until the object is used in a string. This feature is useful
+in cases where the translation locale is unknown until the string is used, even
+though the string might have originally been created when the code was first
+imported.
+
+Normally, you won't have to worry about lazy translations. Just be aware that
+if you examine an object and it claims to be a
+``django.utils.functional.__proxy__`` object, it is a lazy translation.
+Calling ``unicode()`` with the lazy translation as the argument will generate a
+Unicode string in the current locale.
+
+For more details about lazy translation objects, refer to the
+:doc:`internationalization </topics/i18n/index>` documentation.
+
+Useful utility functions
+------------------------
+
+Because some string operations come up again and again, Django ships with a few
+useful functions that should make working with Unicode and bytestring objects
+a bit easier.
+
+Conversion functions
+~~~~~~~~~~~~~~~~~~~~
+
+The ``django.utils.encoding`` module contains a few functions that are handy
+for converting back and forth between Unicode and bytestrings.
+
+    * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')``
+      converts its input to a Unicode string. The ``encoding`` parameter
+      specifies the input encoding. (For example, Django uses this internally
+      when processing form input data, which might not be UTF-8 encoded.) The
+      ``strings_only`` parameter, if set to True, will result in Python
+      numbers, booleans and ``None`` not being converted to a string (they keep
+      their original types). The ``errors`` parameter takes any of the values
+      that are accepted by Python's ``unicode()`` function for its error
+      handling.
+
+      If you pass ``smart_unicode()`` an object that has a ``__unicode__``
+      method, it will use that method to do the conversion.
+
+    * ``force_unicode(s, encoding='utf-8', strings_only=False,
+      errors='strict')`` is identical to ``smart_unicode()`` in almost all
+      cases. The difference is when the first argument is a :ref:`lazy
+      translation <lazy-translations>` instance. While ``smart_unicode()``
+      preserves lazy translations, ``force_unicode()`` forces those objects to a
+      Unicode string (causing the translation to occur). Normally, you'll want
+      to use ``smart_unicode()``. However, ``force_unicode()`` is useful in
+      template tags and filters that absolutely *must* have a string to work
+      with, not just something that can be converted to a string.
+
+    * ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')``
+      is essentially the opposite of ``smart_unicode()``. It forces the first
+      argument to a bytestring. The ``strings_only`` parameter has the same
+      behavior as for ``smart_unicode()`` and ``force_unicode()``. This is
+      slightly different semantics from Python's builtin ``str()`` function,
+      but the difference is needed in a few places within Django's internals.
+
+Normally, you'll only need to use ``smart_unicode()``. Call it as early as
+possible on any input data that might be either Unicode or a bytestring, and
+from then on, you can treat the result as always being Unicode.
+
+URI and IRI handling
+~~~~~~~~~~~~~~~~~~~~
+
+Web frameworks have to deal with URLs (which are a type of IRI_). One
+requirement of URLs is that they are encoded using only ASCII characters.
+However, in an international environment, you might need to construct a
+URL from an IRI_ -- very loosely speaking, a URI that can contain Unicode
+characters. Quoting and converting an IRI to URI can be a little tricky, so
+Django provides some assistance.
+
+    * The function ``django.utils.encoding.iri_to_uri()`` implements the
+      conversion from IRI to URI as required by the specification (`RFC
+      3987`_).
+
+    * The functions ``django.utils.http.urlquote()`` and
+      ``django.utils.http.urlquote_plus()`` are versions of Python's standard
+      ``urllib.quote()`` and ``urllib.quote_plus()`` that work with non-ASCII
+      characters. (The data is converted to UTF-8 prior to encoding.)
+
+These two groups of functions have slightly different purposes, and it's
+important to keep them straight. Normally, you would use ``urlquote()`` on the
+individual portions of the IRI or URI path so that any reserved characters
+such as '&' or '%' are correctly encoded. Then, you apply ``iri_to_uri()`` to
+the full IRI and it converts any non-ASCII characters to the correct encoded
+values.
+
+.. note::
+    Technically, it isn't correct to say that ``iri_to_uri()`` implements the
+    full algorithm in the IRI specification. It doesn't (yet) perform the
+    international domain name encoding portion of the algorithm.
+
+The ``iri_to_uri()`` function will not change ASCII characters that are
+otherwise permitted in a URL. So, for example, the character '%' is not
+further encoded when passed to ``iri_to_uri()``. This means you can pass a
+full URL to this function and it will not mess up the query string or anything
+like that.
+
+An example might clarify things here::
+
+    >>> urlquote(u'Paris & Orléans')
+    u'Paris%20%26%20Orl%C3%A9ans'
+    >>> iri_to_uri(u'/favorites/François/%s' % urlquote(u'Paris & Orléans'))
+    '/favorites/Fran%C3%A7ois/Paris%20%26%20Orl%C3%A9ans'
+
+If you look carefully, you can see that the portion that was generated by
+``urlquote()`` in the second example was not double-quoted when passed to
+``iri_to_uri()``. This is a very important and useful feature. It means that
+you can construct your IRI without worrying about whether it contains
+non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the
+result.
+
+The ``iri_to_uri()`` function is also idempotent, which means the following is
+always true::
+
+    iri_to_uri(iri_to_uri(some_string)) = iri_to_uri(some_string)
+
+So you can safely call it multiple times on the same IRI without risking
+double-quoting problems.
+
+.. _URI: http://www.ietf.org/rfc/rfc2396.txt
+.. _IRI: http://www.ietf.org/rfc/rfc3987.txt
+.. _RFC 3987: IRI_
+
+Models
+======
+
+Because all strings are returned from the database as Unicode strings, model
+fields that are character based (CharField, TextField, URLField, etc) will
+contain Unicode values when Django retrieves data from the database. This
+is *always* the case, even if the data could fit into an ASCII bytestring.
+
+You can pass in bytestrings when creating a model or populating a field, and
+Django will convert it to Unicode when it needs to.
+
+Choosing between ``__str__()`` and ``__unicode__()``
+----------------------------------------------------
+
+One consequence of using Unicode by default is that you have to take some care
+when printing data from the model.
+
+In particular, rather than giving your model a ``__str__()`` method, we
+recommended you implement a ``__unicode__()`` method. In the ``__unicode__()``
+method, you can quite safely return the values of all your fields without
+having to worry about whether they fit into a bytestring or not. (The way
+Python works, the result of ``__str__()`` is *always* a bytestring, even if you
+accidentally try to return a Unicode object).
+
+You can still create a ``__str__()`` method on your models if you want, of
+course, but you shouldn't need to do this unless you have a good reason.
+Django's ``Model`` base class automatically provides a ``__str__()``
+implementation that calls ``__unicode__()`` and encodes the result into UTF-8.
+This means you'll normally only need to implement a ``__unicode__()`` method
+and let Django handle the coercion to a bytestring when required.
+
+Taking care in ``get_absolute_url()``
+-------------------------------------
+
+URLs can only contain ASCII characters. If you're constructing a URL from
+pieces of data that might be non-ASCII, be careful to encode the results in a
+way that is suitable for a URL. The ``django.db.models.permalink()`` decorator
+handles this for you automatically.
+
+If you're constructing a URL manually (i.e., *not* using the ``permalink()``
+decorator), you'll need to take care of the encoding yourself. In this case,
+use the ``iri_to_uri()`` and ``urlquote()`` functions that were documented
+above_. For example::
+
+    from django.utils.encoding import iri_to_uri
+    from django.utils.http import urlquote
+
+    def get_absolute_url(self):
+        url = u'/person/%s/?x=0&y=0' % urlquote(self.location)
+        return iri_to_uri(url)
+
+This function returns a correctly encoded URL even if ``self.location`` is
+something like "Jack visited Paris & Orléans". (In fact, the ``iri_to_uri()``
+call isn't strictly necessary in the above example, because all the
+non-ASCII characters would have been removed in quoting in the first line.)
+
+.. _above: `URI and IRI handling`_
+
+The database API
+================
+
+You can pass either Unicode strings or UTF-8 bytestrings as arguments to
+``filter()`` methods and the like in the database API. The following two
+querysets are identical::
+
+    qs = People.objects.filter(name__contains=u'Å')
+    qs = People.objects.filter(name__contains='\xc3\x85') # UTF-8 encoding of Å
+
+Templates
+=========
+
+You can use either Unicode or bytestrings when creating templates manually::
+
+	from django.template import Template
+	t1 = Template('This is a bytestring template.')
+	t2 = Template(u'This is a Unicode template.')
+
+But the common case is to read templates from the filesystem, and this creates
+a slight complication: not all filesystems store their data encoded as UTF-8.
+If your template files are not stored with a UTF-8 encoding, set the :setting:`FILE_CHARSET`
+setting to the encoding of the files on disk. When Django reads in a template
+file, it will convert the data from this encoding to Unicode. (:setting:`FILE_CHARSET`
+is set to ``'utf-8'`` by default.)
+
+The :setting:`DEFAULT_CHARSET` setting controls the encoding of rendered templates.
+This is set to UTF-8 by default.
+
+Template tags and filters
+-------------------------
+
+A couple of tips to remember when writing your own template tags and filters:
+
+    * Always return Unicode strings from a template tag's ``render()`` method
+      and from template filters.
+
+    * Use ``force_unicode()`` in preference to ``smart_unicode()`` in these
+      places. Tag rendering and filter calls occur as the template is being
+      rendered, so there is no advantage to postponing the conversion of lazy
+      translation objects into strings. It's easier to work solely with Unicode
+      strings at that point.
+
+E-mail
+======
+
+Django's e-mail framework (in ``django.core.mail``) supports Unicode
+transparently. You can use Unicode data in the message bodies and any headers.
+However, you're still obligated to respect the requirements of the e-mail
+specifications, so, for example, e-mail addresses should use only ASCII
+characters.
+
+The following code example demonstrates that everything except e-mail addresses
+can be non-ASCII::
+
+    from django.core.mail import EmailMessage
+
+    subject = u'My visit to Sør-Trøndelag'
+    sender = u'Arnbjörg Ráðormsdóttir <arnbjorg@example.com>'
+    recipients = ['Fred <fred@example.com']
+    body = u'...'
+    EmailMessage(subject, body, sender, recipients).send()
+
+Form submission
+===============
+
+HTML form submission is a tricky area. There's no guarantee that the
+submission will include encoding information, which means the framework might
+have to guess at the encoding of submitted data.
+
+Django adopts a "lazy" approach to decoding form data. The data in an
+``HttpRequest`` object is only decoded when you access it. In fact, most of
+the data is not decoded at all. Only the ``HttpRequest.GET`` and
+``HttpRequest.POST`` data structures have any decoding applied to them. Those
+two fields will return their members as Unicode data. All other attributes and
+methods of ``HttpRequest`` return data exactly as it was submitted by the
+client.
+
+By default, the :setting:`DEFAULT_CHARSET` setting is used as the assumed encoding
+for form data. If you need to change this for a particular form, you can set
+the ``encoding`` attribute on an ``HttpRequest`` instance. For example::
+
+    def some_view(request):
+        # We know that the data must be encoded as KOI8-R (for some reason).
+        request.encoding = 'koi8-r'
+        ...
+
+You can even change the encoding after having accessed ``request.GET`` or
+``request.POST``, and all subsequent accesses will use the new encoding.
+
+Most developers won't need to worry about changing form encoding, but this is
+a useful feature for applications that talk to legacy systems whose encoding
+you cannot control.
+
+Django does not decode the data of file uploads, because that data is normally
+treated as collections of bytes, rather than strings. Any automatic decoding
+there would alter the meaning of the stream of bytes.
diff --git a/parts/django/docs/ref/utils.txt b/parts/django/docs/ref/utils.txt
new file mode 100644
index 0000000..e4ce7c4
--- /dev/null
+++ b/parts/django/docs/ref/utils.txt
@@ -0,0 +1,504 @@
+============
+Django Utils
+============
+
+.. module:: django.utils
+   :synopsis: Django's built-in utilities.
+
+This document covers all stable modules in ``django.utils``. Most of the
+modules in ``django.utils`` are designed for internal use and only the
+following parts can be considered stable and thus backwards compatible as per
+the :ref:`internal release deprecation policy <internal-release-deprecation-policy>`.
+
+``django.utils.cache``
+======================
+
+.. module:: django.utils.cache
+   :synopsis: Helper functions for controlling caching.
+
+This module contains helper functions for controlling caching. It does so by
+managing the ``Vary`` header of responses. It includes functions to patch the
+header of response objects directly and decorators that change functions to do
+that header-patching themselves.
+
+For information on the ``Vary`` header, see `RFC 2616 section 14.44`_.
+
+.. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
+
+Essentially, the ``Vary`` HTTP header defines which headers a cache should take
+into account when building its cache key. Requests with the same path but
+different header content for headers named in ``Vary`` need to get different
+cache keys to prevent delivery of wrong content.
+
+For example, :doc:`internationalization </topics/i18n/index>` middleware would need
+to distinguish caches by the ``Accept-language`` header.
+
+.. function:: patch_cache_control(response, **kwargs)
+
+This function patches the ``Cache-Control`` header by adding all keyword
+arguments to it. The transformation is as follows:
+
+ * All keyword parameter names are turned to lowercase, and underscores
+   are converted to hyphens.
+ * If the value of a parameter is ``True`` (exactly ``True``, not just a
+   true value), only the parameter name is added to the header.
+ * All other parameters are added with their value, after applying
+   ``str()`` to it.
+
+.. function:: get_max_age(response)
+
+Returns the max-age from the response Cache-Control header as an integer (or
+``None`` if it wasn't found or wasn't an integer).
+
+.. function:: patch_response_headers(response, cache_timeout=None)
+
+Adds some useful headers to the given ``HttpResponse`` object:
+
+ * ``ETag``
+ * ``Last-Modified``
+ * ``Expires``
+ * ``Cache-Control``
+
+Each header is only added if it isn't already set.
+
+``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting is
+used by default.
+
+.. function:: add_never_cache_headers(response)
+
+Adds headers to a response to indicate that a page should never be cached.
+
+.. function:: patch_vary_headers(response, newheaders)
+
+Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object.
+``newheaders`` is a list of header names that should be in ``Vary``. Existing
+headers in ``Vary`` aren't removed.
+
+.. function:: get_cache_key(request, key_prefix=None)
+
+Returns a cache key based on the request path. It can be used in the request
+phase because it pulls the list of headers to take into account from the
+global path registry and uses those to build a cache key to check against.
+
+If there is no headerlist stored, the page needs to be rebuilt, so this
+function returns ``None``.
+
+.. function:: learn_cache_key(request, response, cache_timeout=None, key_prefix=None)
+
+Learns what headers to take into account for some request path from the
+response object. It stores those headers in a global path registry so that
+later access to that path will know what headers to take into account without
+building the response object itself. The headers are named in the ``Vary``
+header of the response, but we want to prevent response generation.
+
+The list of headers to use for cache key generation is stored in the same cache
+as the pages themselves. If the cache ages some data out of the cache, this
+just means that we have to build the response once to get at the Vary header
+and so at the list of headers to use for the cache key.
+
+SortedDict
+==========
+
+.. module:: django.utils.datastructures
+   :synopsis: A dictionary that keeps its keys in the order in which they're inserted.
+
+.. class:: django.utils.datastructures.SortedDict
+
+Methods
+-------
+
+Extra methods that ``SortedDict`` adds to the standard Python ``dict`` class.
+
+.. method:: insert(index, key, value)
+
+Inserts the key, value pair before the item with the given index.
+
+.. method:: value_for_index(index)
+
+Returns the value of the item at the given zero-based index.
+
+Creating new SortedDict
+-----------------------
+
+Creating a new ``SortedDict`` must be done in a way where ordering is
+guaranteed. For example::
+
+    SortedDict({'b': 1, 'a': 2, 'c': 3})
+
+will not work. Passing in a basic Python ``dict`` could produce unreliable
+results. Instead do::
+
+    SortedDict([('b', 1), ('a', 2), ('c', 3)])
+
+``django.utils.encoding``
+=========================
+
+.. module:: django.utils.encoding
+   :synopsis: A series of helper classes and function to manage character encoding.
+
+.. class:: StrAndUnicode
+
+A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8 bytestring.
+Useful as a mix-in.
+
+.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+Returns a ``unicode`` object representing ``s``. Treats bytestrings using the
+'encoding' codec.
+
+If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.
+
+.. function:: is_protected_type(obj)
+
+Determine if the object instance is of a protected type.
+
+Objects of protected types are preserved as-is when passed to
+``force_unicode(strings_only=True)``.
+
+.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')
+
+Similar to ``smart_unicode``, except that lazy instances are resolved to strings,
+rather than kept as lazy objects.
+
+If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.
+
+.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict')
+
+Returns a bytestring version of ``s``, encoded as specified in ``encoding``.
+
+If ``strings_only`` is ``True``, don't convert (some) non-string-like objects.
+
+.. function:: iri_to_uri(iri)
+
+Convert an Internationalized Resource Identifier (IRI) portion to a URI portion
+that is suitable for inclusion in a URL.
+
+This is the algorithm from section 3.1 of `RFC 3987`_.  However, since we are
+assuming input is either UTF-8 or unicode already, we can simplify things a
+little from the full method.
+
+.. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt
+
+Returns an ASCII string containing the encoded result.
+
+``django.utils.feedgenerator``
+==============================
+
+.. module:: django.utils.feedgenerator
+   :synopsis: Syndication feed generation library -- used for generating RSS, etc.
+
+Sample usage::
+
+    >>> from django.utils import feedgenerator
+    >>> feed = feedgenerator.Rss201rev2Feed(
+    ...     title=u"Poynter E-Media Tidbits",
+    ...     link=u"http://www.poynter.org/column.asp?id=31",
+    ...     description=u"A group Weblog by the sharpest minds in online media/journalism/publishing.",
+    ...     language=u"en",
+    ... )
+    >>> feed.add_item(
+    ...     title="Hello",
+    ...     link=u"http://www.holovaty.com/test/",
+    ...     description="Testing."
+    ... )
+    >>> fp = open('test.rss', 'w')
+    >>> feed.write(fp, 'utf-8')
+    >>> fp.close()
+
+For simplifying the selection of a generator use ``feedgenerator.DefaultFeed``
+which is currently ``Rss201rev2Feed``
+
+For definitions of the different versions of RSS, see:
+http://diveintomark.org/archives/2004/02/04/incompatible-rss
+
+.. function:: get_tag_uri(url, date)
+
+Creates a TagURI.
+
+See http://diveintomark.org/archives/2004/05/28/howto-atom-id
+
+SyndicationFeed
+---------------
+
+.. class:: SyndicationFeed
+
+Base class for all syndication feeds. Subclasses should provide write().
+
+Methods
+~~~~~~~
+
+.. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs])
+
+Adds an item to the feed. All args are expected to be Python ``unicode``
+objects except ``pubdate``, which is a ``datetime.datetime`` object, and
+``enclosure``, which is an instance of the ``Enclosure`` class.
+
+.. method:: num_items()
+
+.. method:: root_attributes()
+
+Return extra attributes to place on the root (i.e. feed/channel) element.
+Called from write().
+
+.. method:: add_root_elements(handler)
+
+Add elements in the root (i.e. feed/channel) element. Called from write().
+
+.. method:: item_attributes(item)
+
+Return extra attributes to place on each item (i.e. item/entry) element.
+
+.. method:: add_item_elements(handler, item)
+
+Add elements on each item (i.e. item/entry) element.
+
+.. method:: write(outfile, encoding)
+
+Outputs the feed in the given encoding to ``outfile``, which is a file-like
+object. Subclasses should override this.
+
+.. method:: writeString(encoding)
+
+Returns the feed in the given encoding as a string.
+
+.. method:: latest_post_date()
+
+Returns the latest item's ``pubdate``. If none of them have a ``pubdate``,
+this returns the current date/time.
+
+Enclosure
+---------
+
+.. class:: Enclosure
+
+Represents an RSS enclosure
+
+RssFeed
+-------
+
+.. class:: RssFeed(SyndicationFeed)
+
+Rss201rev2Feed
+--------------
+
+.. class:: Rss201rev2Feed(RssFeed)
+
+Spec: http://blogs.law.harvard.edu/tech/rss
+
+Atom1Feed
+---------
+
+.. class:: Atom1Feed(SyndicationFeed)
+
+Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
+
+``django.utils.http``
+=====================
+
+.. module:: django.utils.http
+   :synopsis: HTTP helper functions. (URL encoding, cookie handling, ...)
+
+.. function:: urlquote(url, safe='/')
+
+A version of Python's ``urllib.quote()`` function that can operate on unicode
+strings. The url is first UTF-8 encoded before quoting. The returned string
+can safely be used as part of an argument to a subsequent ``iri_to_uri()``
+call without double-quoting occurring. Employs lazy execution.
+
+.. function:: urlquote_plus(url, safe='')
+
+A version of Python's urllib.quote_plus() function that can operate on unicode
+strings. The url is first UTF-8 encoded before quoting. The returned string can
+safely be used as part of an argument to a subsequent iri_to_uri() call without
+double-quoting occurring. Employs lazy execution.
+
+.. function:: urlencode(query, doseq=0)
+
+A version of Python's urllib.urlencode() function that can operate on unicode
+strings. The parameters are first case to UTF-8 encoded strings and then
+encoded as per normal.
+
+.. function:: cookie_date(epoch_seconds=None)
+
+Formats the time to ensure compatibility with Netscape's cookie standard.
+
+Accepts a floating point number expressed in seconds since the epoch, in UTC -
+such as that outputted by ``time.time()``. If set to ``None``, defaults to the current
+time.
+
+Outputs a string in the format ``Wdy, DD-Mon-YYYY HH:MM:SS GMT``.
+
+.. function:: http_date(epoch_seconds=None)
+
+Formats the time to match the RFC 1123 date format as specified by HTTP
+`RFC 2616`_ section 3.3.1.
+
+.. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt
+
+Accepts a floating point number expressed in seconds since the epoch, in UTC -
+such as that outputted by ``time.time()``. If set to ``None``, defaults to the current
+time.
+
+Outputs a string in the format ``Wdy, DD Mon YYYY HH:MM:SS GMT``.
+
+.. function:: base36_to_int(s)
+
+Converted a base 36 string to an integer
+
+.. function:: int_to_base36(i)
+
+Converts an integer to a base36 string
+
+``django.utils.safestring``
+===========================
+
+.. module:: django.utils.safestring
+   :synopsis: Functions and classes for working with strings that can be displayed safely without further escaping in HTML.
+
+Functions and classes for working with "safe strings": strings that can be
+displayed safely without further escaping in HTML. Marking something as a "safe
+string" means that the producer of the string has already turned characters
+that should not be interpreted by the HTML engine (e.g. '<') into the
+appropriate entities.
+
+.. class:: SafeString
+
+A string subclass that has been specifically marked as "safe" (requires no
+further escaping) for HTML output purposes.
+
+.. class:: SafeUnicode
+
+A unicode subclass that has been specifically marked as "safe" for HTML output
+purposes.
+
+.. function:: mark_safe(s)
+
+Explicitly mark a string as safe for (HTML) output purposes. The returned
+object can be used everywhere a string or unicode object is appropriate.
+
+Can be called multiple times on a single string.
+
+.. function:: mark_for_escaping(s)
+
+Explicitly mark a string as requiring HTML escaping upon output. Has no effect
+on ``SafeData`` subclasses.
+
+Can be called multiple times on a single string (the resulting escaping is only
+applied once).
+
+``django.utils.translation``
+============================
+
+.. module:: django.utils.translation
+   :synopsis: Internationalization support.
+
+For a complete discussion on the usage of the following see the
+:doc:`Internationalization documentation </topics/i18n/internationalization>`.
+
+.. function:: gettext(message)
+
+Translates ``message`` and returns it in a UTF-8 bytestring
+
+.. function:: ugettext(message)
+
+Translates ``message`` and returns it in a unicode string
+
+.. function:: gettext_lazy(message)
+.. function:: ugettext_lazy(message)
+
+Same as the non-lazy versions above, but using lazy execution.
+
+See :ref:`lazy translations documentation <lazy-translations>`.
+
+.. function:: gettext_noop(message)
+
+Marks strings for translation but doesn't translate them now. This can be used
+to store strings in global variables that should stay in the base language
+(because they might be used externally) and will be translated later.
+
+.. function:: ngettext(singular, plural, number)
+
+Translates ``singular`` and ``plural`` and returns the appropriate string
+based on ``number`` in a UTF-8 bytestring
+
+.. function:: ungettext(singular, plural, number)
+
+Translates ``singular`` and ``plural`` and returns the appropriate string based
+on ``number`` in a unicode string
+
+.. function:: ngettext_lazy(singular, plural, number)
+.. function:: ungettext_lazy(singular, plural, number)
+
+Same as the non-lazy versions above, but using lazy execution.
+
+See :ref:`lazy translations documentation <lazy-translations>`.
+
+.. function:: string_concat(*strings)
+
+Lazy variant of string concatenation, needed for translations that are
+constructed from multiple parts.
+
+.. function:: activate(language)
+
+Fetches the translation object for a given tuple of application name and
+language and installs it as the current translation object for the current
+thread.
+
+.. function:: deactivate()
+
+De-installs the currently active translation object so that further _ calls will
+resolve against the default translation object, again.
+
+.. function:: deactivate_all()
+
+Makes the active translation object a NullTranslations() instance. This is
+useful when we want delayed translations to appear as the original string for
+some reason.
+
+.. function:: get_language()
+
+Returns the currently selected language code.
+
+.. function:: get_language_bidi()
+
+Returns selected language's BiDi layout:
+
+ * ``False`` = left-to-right layout
+ * ``True`` = right-to-left layout
+
+.. function:: get_date_formats()
+
+Checks whether translation files provide a translation for some technical
+message ID to store date and time formats. If it doesn't contain one, the
+formats provided in the settings will be used.
+
+.. function:: get_language_from_request(request)
+
+Analyzes the request to find what language the user wants the system to show.
+Only languages listed in settings.LANGUAGES are taken into account. If the user
+requests a sublanguage where we have a main language, we send out the main
+language.
+
+.. function:: to_locale(language)
+
+Turns a language name (en-us) into a locale name (en_US).
+
+.. function:: templatize(src)
+
+Turns a Django template into something that is understood by xgettext. It does
+so by translating the Django translation tags into standard gettext function
+invocations.
+
+``django.utils.tzinfo``
+=======================
+
+.. module:: django.utils.tzinfo
+   :synopsis: Implementation of ``tzinfo`` classes for use with ``datetime.datetime``.
+
+.. class:: FixedOffset
+
+Fixed offset in minutes east from UTC.
+
+.. class:: LocalTimezone
+
+Proxy timezone information from time module.
diff --git a/parts/django/docs/ref/validators.txt b/parts/django/docs/ref/validators.txt
new file mode 100644
index 0000000..0451f65
--- /dev/null
+++ b/parts/django/docs/ref/validators.txt
@@ -0,0 +1,158 @@
+==========
+Validators
+==========
+
+.. versionadded:: 1.2
+.. module:: django.core.validators
+    :synopsis: Validation utilities and base classes
+
+Writing validators
+==================
+
+A validator is a callable that takes a value and raises a
+:exc:`~django.core.exceptions.ValidationError` if it doesn't meet some
+criteria. Validators can be useful for re-using validation logic between
+different types of fields.
+
+For example, here's a validator that only allows even numbers::
+
+    from django.core.exceptions import ValidationError
+
+    def validate_even(value):
+        if value % 2 != 0:
+            raise ValidationError(u'%s is not an even number' % value)
+
+You can add this to a model field via the field's :attr:`~django.db.models.Field.validators`
+argument::
+
+    from django.db import models
+
+    class MyModel(models.Model):
+        even_field = models.IntegerField(validators=[validate_even])
+
+Because values are converted to Python before validators are run, you can even
+use the same validator with forms::
+
+    from django import forms
+
+    class MyForm(forms.Form):
+        even_field = forms.IntegerField(validators=[validate_even])
+
+How validators are run
+======================
+
+See the :doc:`form validation </ref/forms/validation>` for more information on
+how validators are run in forms, and :ref:`Validating objects
+<validating-objects>` for how they're run in models. Note that validators will
+not be run automatically when you save a model, but if you are using a
+:class:`~django.forms.ModelForm`, it will run your validators on any fields
+that are included in your form. See the
+:doc:`ModelForm documentation </topics/forms/modelforms>` for information on
+how model validation interacts with forms.
+
+Built-in validators
+===================
+
+The :mod:`django.core.validators` module contains a collection of callable
+validators for use with model and form fields. They're used internally but
+are available for use with your own fields, too. They can be used in addition
+to, or in lieu of custom ``field.clean()`` methods.
+
+``RegexValidator``
+------------------
+.. class:: RegexValidator(regex, [message=None, code=None])
+
+    .. attribute:: regex
+
+        The regular expression pattern to search for the provided ``value``,
+        or a pre-compiled regular expression. Raises a
+        :exc:`~django.core.exceptions.ValidationError` with :attr:`.message`
+        and :attr:`.code` if no match is found.
+
+    .. attribute:: message
+
+        The error message used by :exc:`~django.core.exceptions.ValidationError`
+        if validation fails. If no :attr:`.message` is specified, a generic
+        ``"Enter a valid value"`` message is used. Default value: ``None``.
+
+    .. attribute:: code
+
+        The error code used by :exc:`~django.core.exceptions.ValidationError`
+        if validation fails. If :attr:`.code` is not specified, ``"invalid"``
+        is used. Default value: ``None``.
+
+``URLValidator``
+----------------
+.. class:: URLValidator([verify_exists=False, validator_user_agent=URL_VALIDATOR_USER_AGENT])
+
+    A :class:`RegexValidator` that ensures a value looks like a URL and
+    optionally verifies that the URL actually exists (i.e., doesn't return a
+    404 status code). Raises an error code of ``'invalid'`` if it doesn't look
+    like a URL, and a code of ``'invalid_link'`` if it doesn't exist.
+
+    .. attribute:: verify_exists
+
+        Default value: ``False``. If set to ``True``, this validator checks
+        that the URL actually exists.
+
+    .. attribute:: validator_user_agent
+
+        If :attr:`.verify_exists` is ``True``, Django uses the value of
+        :attr:`.validator_user_agent` as the "User-agent" for the request. This
+        defaults to :setting:`settings.URL_VALIDATOR_USER_AGENT <URL_VALIDATOR_USER_AGENT>`.
+
+``validate_email``
+------------------
+.. data:: validate_email
+
+    A :class:`RegexValidator` instance that ensures a value looks like an
+    e-mail address.
+
+``validate_slug``
+-----------------
+.. data:: validate_slug
+
+    A :class:`RegexValidator` instance that ensures a value consists of only
+    letters, numbers, underscores or hyphens.
+
+``validate_ipv4_address``
+-------------------------
+.. data:: validate_ipv4_address
+
+    A :class:`RegexValidator` instance that ensures a value looks like an IPv4
+    address.
+
+``validate_comma_separated_integer_list``
+-----------------------------------------
+.. data:: validate_comma_separated_integer_list
+
+    A :class:`RegexValidator` instance that ensures a value is a
+    comma-separated list of integers.
+
+``MaxValueValidator``
+---------------------
+.. class:: MaxValueValidator(max_value)
+
+    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
+    ``'max_value'`` if ``value`` is greater than ``max_value``.
+
+``MinValueValidator``
+---------------------
+.. class:: MinValueValidator(min_value)
+
+    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
+    ``'min_value'`` if ``value`` is less than ``min_value``.
+
+``MaxLengthValidator``
+----------------------
+.. class:: MaxLengthValidator(max_length)
+
+    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
+    ``'max_length'`` if the length of ``value`` is greater than ``max_length``.
+
+``MinLengthValidator``
+----------------------
+.. class:: MinLengthValidator(min_length)
+
+    Raises a :exc:`~django.core.exceptions.ValidationError` with a code of
+    ``'min_length'`` if the length of ``value`` is less than ``min_length``.