[soc2010/app-loading] merged trunkarchive/soc2010/app-loadingsoc2010/app-loading

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2010/app-loading@13818 bcc190cf-cafb-0310-a4f2-bffc1f526a37

21 files changed, 275 insertions, 213 deletions

diff --git a/docs/releases/0.95.txt b/docs/releases/0.95.txt
index b74160128b..7409bff1c0 100644
--- a/docs/releases/0.95.txt
+++ b/docs/releases/0.95.txt
@@ -1,5 +1,3 @@
-.. _releases-0.95:
-
 =================================
 Django version 0.95 release notes
 =================================
@@ -100,7 +98,7 @@ Problem reports and getting help
 ================================
 
 Need help resolving a problem with Django? The documentation in the distribution
-is also available online_ at the `Django Web site`_. The :ref:`FAQ <faq-index>`
+is also available online_ at the `Django Web site`_. The :doc:`FAQ </faq/index>`
 document is especially recommended, as it contains a number of issues that come
 up time and again.
 
diff --git a/docs/releases/0.96.txt b/docs/releases/0.96.txt
index 8d795acebd..1224360e3f 100644
--- a/docs/releases/0.96.txt
+++ b/docs/releases/0.96.txt
@@ -1,5 +1,3 @@
-.. _releases-0.96:
-
 =================================
 Django version 0.96 release notes
 =================================
diff --git a/docs/releases/1.0-alpha-1.txt b/docs/releases/1.0-alpha-1.txt
index caee575cb2..82846be44a 100644
--- a/docs/releases/1.0-alpha-1.txt
+++ b/docs/releases/1.0-alpha-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0-alpha-1:
-
 ================================
 Django 1.0 alpha release notes
 ================================
@@ -34,7 +32,7 @@ Refactored admin application (newforms-admin)
     documentation for the admin application is available online in the
     official Django documentation:
 
-        :ref:`admin reference <ref-contrib-admin>`
+        :doc:`admin reference </ref/contrib/admin/index>`
 
 Improved Unicode handling
     Django's internals have been refactored to use Unicode throughout;
@@ -45,7 +43,7 @@ Improved Unicode handling
     Unicode gracefully. Details are available in Django's
     Unicode-handling documentation:
 
-         :ref:`unicode reference <ref-unicode>`
+         :doc:`unicode reference </ref/unicode>`
 
 An improved Django ORM
     Django's object-relational mapper -- the component which provides
@@ -156,7 +154,7 @@ to join the discussions there.
 Django's online documentation also includes pointers on how to
 contribute to Django:
 
-    :ref:`contributing to Django <internals-contributing>`
+    :doc:`contributing to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing
 documentation or simply triaging tickets and helping to test proposed
diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt
index 5cbd777204..83e2e2e14a 100644
--- a/docs/releases/1.0-alpha-2.txt
+++ b/docs/releases/1.0-alpha-2.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0-alpha-2:
-
 ================================
 Django 1.0 alpha 2 release notes
 ================================
@@ -21,8 +19,8 @@ What's new in Django 1.0 alpha 2
 
 Django's development trunk has been the site of nearly constant activity over
 the past year, with several major new features landing since the 0.96 release.
-For features which were new as of Django 1.0 alpha 1, see :ref:`the 1.0 alpha 1
-release notes <releases-1.0-alpha-1`. Since the 1.0 alpha 1 release several new
+For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1
+release notes </releases/1.0-alpha-1>`. Since the 1.0 alpha 1 release several new
 features have landed, including:
 
 ``django.contrib.gis`` (`GeoDjango`_)
@@ -37,8 +35,8 @@ features have landed, including:
 Pluggable file storage
     Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
     pluggable file-storage backends, allowing extensive customization of where
-    and how uploaded files get stored by Django. For details, see :ref:`the
-    files documentation <topics-files>`; big thanks go to Marty Alchin for
+    and how uploaded files get stored by Django. For details, see :doc:`the
+    files documentation </topics/files>`; big thanks go to Marty Alchin for
     putting in the hard work to get this completed.
 
 Jython compatibility
@@ -51,11 +49,11 @@ Jython compatibility
 
 There are many other new features and improvements in this release, including
 two major performance boosts: strings marked for translation using
-:ref:`Django's internationalization system <topics-i18n>` now consume far less
+:doc:`Django's internationalization system </topics/i18n/index>` now consume far less
 memory, and Django's internal dispatcher -- which is invoked frequently during
 request/response processing and when working with Django's object-relational
 mapper -- is now significantly faster.
-    
+
 .. _GeoDjango: http://geodjango.org/
 .. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system
 .. _Its documentation: http://geodjango.org/docs/
@@ -131,7 +129,7 @@ to join the discussions there.
 Django's online documentation also includes pointers on how to
 contribute to Django:
 
-    :ref:`contributing to Django <internals-contributing>`
+    :doc:`contributing to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing
 documentation or simply triaging tickets and helping to test proposed
diff --git a/docs/releases/1.0-beta-2.txt b/docs/releases/1.0-beta-2.txt
index 89b9233576..eabd6b744b 100644
--- a/docs/releases/1.0-beta-2.txt
+++ b/docs/releases/1.0-beta-2.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0-beta-2:
-
 ===============================
 Django 1.0 beta 2 release notes
 ===============================
@@ -21,11 +19,11 @@ What's new in Django 1.0 beta 2
 Django's development trunk has been the site of nearly constant
 activity over the past year, with several major new features landing
 since the 0.96 release.  For features which were new as of Django 1.0
-alpha 1, see :ref:`the 1.0 alpha 1 release notes
-<releases-1.0-alpha-1>`. For features which were new as of Django 1.0
-alpha 2, see :ref:`the 1.0 alpha 2 release notes
-<releases-1.0-alpha-2>`. For features which were new as of Django 1.0
-beta 1, see :ref:`the 1.0 beta 1 release notes <releases-1.0-beta>`.
+alpha 1, see :doc:`the 1.0 alpha 1 release notes
+</releases/1.0-alpha-1>`. For features which were new as of Django 1.0
+alpha 2, see :doc:`the 1.0 alpha 2 release notes
+</releases/1.0-alpha-2>`. For features which were new as of Django 1.0
+beta 1, see :doc:`the 1.0 beta 1 release notes </releases/1.0-beta>`.
 
 This beta release includes two major features:
 
@@ -33,9 +31,9 @@ Refactored ``django.contrib.comments``
     As part of a Google Summer of Code project, Thejaswi Puthraya
     carried out a major rewrite and refactoring of Django's bundled
     comment system, greatly increasing its flexibility and
-    customizability. :ref:`Full documentation
-    <ref-contrib-comments-index>` is available, as well as :ref:`an
-    upgrade guide <ref-contrib-comments-upgrade>` if you were using
+    customizability. :doc:`Full documentation
+    </ref/contrib/comments/index>` is available, as well as :doc:`an
+    upgrade guide </ref/contrib/comments/upgrade>` if you were using
     the previous incarnation of the comments application..
 
 Refactored documentation
@@ -59,8 +57,8 @@ Also, as part of its ongoing deprecation process, Django's old
 form-handling system has been removed; this means ``django.oldforms``
 no longer exists, and its various API hooks (such as automatic
 manipulators) are no longer present in Django. This system has been
-completely replaced by :ref:`the new form-handling system
-<topics-forms-index>` in ``django.forms``.
+completely replaced by :doc:`the new form-handling system
+</topics/forms/index>` in ``django.forms``.
 
 
 The Django 1.0 roadmap
@@ -114,7 +112,7 @@ to join the discussions there.
 Django's online documentation also includes pointers on how to
 contribute to Django:
 
-    :ref:`contributing to Django <internals-contributing>`
+    :doc:`contributing to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing
 documentation or simply triaging tickets and helping to test proposed
diff --git a/docs/releases/1.0-beta.txt b/docs/releases/1.0-beta.txt
index c1957a75a4..9e07e6c03f 100644
--- a/docs/releases/1.0-beta.txt
+++ b/docs/releases/1.0-beta.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0-beta:
-
 ===============================
 Django 1.0 beta 1 release notes
 ===============================
@@ -20,9 +18,9 @@ What's new in Django 1.0 beta 1
 
 Django's development trunk has been the site of nearly constant activity over
 the past year, with several major new features landing since the 0.96 release.
-For features which were new as of Django 1.0 alpha 1, see :ref:`the 1.0 alpha 1
-release notes <releases-1.0-alpha-1>`. For features which were new as of Django
-1.0 alpha 2, see :ref:`the 1.0 alpha 2 release notes <releases-1.0-alpha-2>`.
+For features which were new as of Django 1.0 alpha 1, see :doc:`the 1.0 alpha 1
+release notes </releases/1.0-alpha-1>`. For features which were new as of Django
+1.0 alpha 2, see :doc:`the 1.0 alpha 2 release notes </releases/1.0-alpha-2>`.
 
 This beta release does not contain any major new features, but does
 include several smaller updates and improvements to Django:
@@ -38,7 +36,7 @@ Improved flexibility in the admin
     interface (``django.contrib.admin``), introduced in Django 1.0
     alpha 1, two new hooks have been added to allow customized pre-
     and post-save handling of model instances in the admin. Full
-    details are in :ref:`the admin documentation <ref-contrib-admin>`.
+    details are in :doc:`the admin documentation </ref/contrib/admin/index>`.
 
 ``INSERT``/``UPDATE`` distinction
     Although Django's default behavior of having a model's ``save()``
@@ -59,7 +57,7 @@ Split ``CacheMiddleware``
    flexibility for situations where combining these functions into a
    single middleware posed problems. Full details, including updated
    notes on appropriate use, are in 
-   :ref:`the caching documentation <topics-cache>`.
+   :doc:`the caching documentation </topics/cache>`.
 
 Removal of deprecated features
     A number of features and methods which had previously been marked
@@ -148,7 +146,7 @@ to join the discussions there.
 Django's online documentation also includes pointers on how to
 contribute to Django:
 
-    :ref:`contributing to Django <internals-contributing>`
+    :doc:`contributing to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing
 documentation or simply triaging tickets and helping to test proposed
diff --git a/docs/releases/1.0-porting-guide.txt b/docs/releases/1.0-porting-guide.txt
index f87da1c8d0..95b9efe255 100644
--- a/docs/releases/1.0-porting-guide.txt
+++ b/docs/releases/1.0-porting-guide.txt
@@ -13,7 +13,7 @@ Changes`_ for a list of a bunch of less-common compatibility issues.
 
 .. seealso::
 
-    The :ref:`1.0 release notes <releases-1.0>`. That document explains the new
+    The :doc:`1.0 release notes </releases/1.0>`. That document explains the new
     features in 1.0 more deeply; the porting guide is more concerned with
     helping you quickly update your code.
 
@@ -31,7 +31,7 @@ now uses Unicode strings throughout. In most places, raw strings will continue
 to work, but updating to use Unicode literals will prevent some obscure
 problems.
 
-See :ref:`ref-unicode` for full details.
+See :doc:`/ref/unicode` for full details.
 
 Models
 ------
@@ -211,7 +211,7 @@ New (1.0)::
       can be found on the `NewformsAdminBranch wiki page`__
 
     * The new admin comes with a ton of new features; you can read about them in
-      the :ref:`admin documentation <ref-contrib-admin>`.
+      the :doc:`admin documentation </ref/contrib/admin/index>`.
 
     __ http://code.djangoproject.com/wiki/NewformsAdminBranch
 
@@ -271,7 +271,7 @@ New::
 
 If you're using the old forms system (formerly known as ``django.forms`` and
 ``django.oldforms``), you'll have to rewrite your forms. A good place to start
-is the :ref:`forms documentation <topics-forms-index>`
+is the :doc:`forms documentation </topics/forms/index>`
 
 Handle uploaded files using the new API
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -318,7 +318,7 @@ Old (0.96)                           New (1.0)
 
 Note that the ``width`` and ``height`` attributes only make sense for
 :class:`~django.db.models.ImageField` fields. More details can be found in the
-:ref:`model API <ref-models-fields>` documentation.
+:doc:`model API </ref/models/fields>` documentation.
 
 Use ``Paginator`` instead of ``ObjectPaginator``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -392,7 +392,7 @@ Comments
 
 If you were using Django 0.96's ``django.contrib.comments`` app, you'll need to
 upgrade to the new comments app introduced in 1.0. See
-:ref:`ref-contrib-comments-upgrade` for details.
+:doc:`/ref/contrib/comments/upgrade` for details.
 
 Template tags
 -------------
diff --git a/docs/releases/1.0.1.txt b/docs/releases/1.0.1.txt
index ce101bed03..780dc53c1f 100644
--- a/docs/releases/1.0.1.txt
+++ b/docs/releases/1.0.1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0.1:
-
 ==========================
 Django 1.0.1 release notes
 ==========================
diff --git a/docs/releases/1.0.2.txt b/docs/releases/1.0.2.txt
index 136a833f05..b34522a08d 100644
--- a/docs/releases/1.0.2.txt
+++ b/docs/releases/1.0.2.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0.2:
-
 ==========================
 Django 1.0.2 release notes
 ==========================
@@ -9,7 +7,7 @@ Welcome to Django 1.0.2!
 This is the second "bugfix" release in the Django 1.0 series,
 improving the stability and performance of the Django 1.0 codebase. As
 such, Django 1.0.2 contains no new features (and, pursuant to
-:ref:`our compatibility policy <misc-api-stability>`, maintains backwards compatibility with Django
+:doc:`our compatibility policy </misc/api-stability>`, maintains backwards compatibility with Django
 1.0.0), but does contain a number of fixes and other
 improvements. Django 1.0.2 is a recommended upgrade for any
 development or deployment currently using or targeting Django 1.0.
@@ -27,7 +25,7 @@ Django's unit-test suite.
 Django 1.0.2 contains updated packaging scripts, and the release
 package contains the directories omitted from Django 1.0.1. As such,
 this release contains all of the fixes and improvements from Django
-1.0.1; see :ref:`the Django 1.0.1 release notes <releases-1.0.1>` for
+1.0.1; see :doc:`the Django 1.0.1 release notes </releases/1.0.1>` for
 details.
 
 Additionally, in the period since Django 1.0.1 was released:
diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt
index 6827a62cc8..359490aad3 100644
--- a/docs/releases/1.0.txt
+++ b/docs/releases/1.0.txt
@@ -1,5 +1,3 @@
-.. _releases-1.0:
-
 ========================
 Django 1.0 release notes
 ========================
@@ -24,12 +22,12 @@ contributions overtake those made privately.
 Stability and forwards-compatibility
 ====================================
 
-:ref:`The release of Django 1.0 <releases-1.0>` comes with a promise of API
+:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
 stability and forwards-compatibility. In a nutshell, this means that code you
 develop against Django 1.0 will continue to work against 1.1 unchanged, and you
 should need to make only minor changes for any 1.X release.
 
-See the :ref:`API stability guide <misc-api-stability>` for full details.
+See the :doc:`API stability guide </misc/api-stability>` for full details.
 
 Backwards-incompatible changes
 ==============================
@@ -42,7 +40,7 @@ detailed porting guide:
    :maxdepth: 1
 
    1.0-porting-guide
-   
+
 A complete list of backwards-incompatible changes can be found at
 http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges.
 
@@ -60,9 +58,9 @@ In fact, new documentation is one of our favorite features of Django 1.0, so we
 might as well start there. First, there's a new documentation site:
 
     http://docs.djangoproject.com/
-    
+
 The documentation has been greatly improved, cleaned up, and generally made
-awesome. There's now dedicated search, indexes, and more. 
+awesome. There's now dedicated search, indexes, and more.
 
 We can't possibly document everything that's new in 1.0, but the documentation
 will be your definitive guide. Anywhere you see something like:
@@ -85,7 +83,7 @@ Django's new form-handling library (introduced in the 0.96 release as
 redesigned with extensibility and customization in mind. Full documentation for
 the admin application is available online in the official Django documentation:
 
-See the :ref:`admin reference <ref-contrib-admin>` for details
+See the :doc:`admin reference </ref/contrib/admin/index>` for details
 
 Improved Unicode handling
 -------------------------
@@ -97,7 +95,7 @@ interoperability with third-party libraries and systems which may or may not
 handle Unicode gracefully. Details are available in Django's Unicode-handling
 documentation.
 
-See :ref:`ref-unicode`.
+See :doc:`/ref/unicode`.
 
 An improved ORM
 ---------------
@@ -142,8 +140,8 @@ Pluggable file storage
 
 Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
 pluggable file-storage backends, allowing extensive customization of where and
-how uploaded files get stored by Django. For details, see :ref:`the files
-documentation <topics-files>`; big thanks go to Marty Alchin for putting in the
+how uploaded files get stored by Django. For details, see :doc:`the files
+documentation </topics/files>`; big thanks go to Marty Alchin for putting in the
 hard work to get this completed.
 
 Jython compatibility
@@ -155,7 +153,7 @@ Django's codebase has been refactored to remove incompatibilities with
 on the Java Virtual Machine. Django is now compatible with the forthcoming
 Jython 2.5 release.
 
-See :ref:`howto-jython`.
+See :doc:`/howto/jython`.
 
 .. _Jython: http://www.jython.org/
 
@@ -187,17 +185,17 @@ handle the two parts of caching (inserting into and reading from the cache)
 separately, offering additional flexibility for situations where combining these
 functions into a single middleware posed problems.
 
-Full details, including updated notes on appropriate use, are in :ref:`the
-caching documentation <topics-cache>`.
+Full details, including updated notes on appropriate use, are in :doc:`the
+caching documentation </topics/cache>`.
 
 Refactored ``django.contrib.comments``
 --------------------------------------
 
 As part of a Google Summer of Code project, Thejaswi Puthraya carried out a
 major rewrite and refactoring of Django's bundled comment system, greatly
-increasing its flexibility and customizability. :ref:`Full documentation
-<ref-contrib-comments-index>` is available, as well as :ref:`an upgrade guide
-<ref-contrib-comments-upgrade>` if you were using the previous incarnation of
+increasing its flexibility and customizability. :doc:`Full documentation
+</ref/contrib/comments/index>` is available, as well as :doc:`an upgrade guide
+</ref/contrib/comments/upgrade>` if you were using the previous incarnation of
 the comments application.
 
 Removal of deprecated features
@@ -240,7 +238,7 @@ Caveats with support of certain databases
 -----------------------------------------
 
 Django attempts to support as many features as possible on all database
-backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :ref:`notes on supported database <ref-databases>`:
+backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :doc:`notes on supported database </ref/databases>`:
 
     - :ref:`mysql-notes`
     - :ref:`sqlite-notes`
diff --git a/docs/releases/1.1-alpha-1.txt b/docs/releases/1.1-alpha-1.txt
index 664c354561..b15a2a423c 100644
--- a/docs/releases/1.1-alpha-1.txt
+++ b/docs/releases/1.1-alpha-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.1-alpha-1:
-
 ================================
 Django 1.1 alpha 1 release notes
 ================================
@@ -37,8 +35,8 @@ results of the aggregate directly, or else annotate the objects in a
 :class:`QuerySet` with the results of the aggregate query.
 
 This feature is available as new :meth:`QuerySet.aggregate()`` and
-:meth:`QuerySet.annotate()`` methods, and is covered in detail in :ref:`the ORM
-aggregation documentation <topics-db-aggregation>`
+:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM
+aggregation documentation </topics/db/aggregation>`
 
 Query expressions
 ~~~~~~~~~~~~~~~~~
@@ -53,7 +51,7 @@ Performance improvements
 
 .. currentmodule:: django.test
 
-Tests written using Django's :ref:`testing framework <topics-testing>` now run
+Tests written using Django's :doc:`testing framework </topics/testing>` now run
 dramatically faster (as much as 10 times faster in many cases).
 
 This was accomplished through the introduction of transaction-based tests: when
@@ -68,7 +66,7 @@ Other improvements
 
 Other new features and changes introduced since Django 1.0 include:
 
-* The :ref:`CSRF protection middleware <ref-contrib-csrf>` has been split into
+* The :doc:`CSRF protection middleware </ref/contrib/csrf>` has been split into
   two classes -- ``CsrfViewMiddleware`` checks incoming requests, and
   ``CsrfResponseMiddleware`` processes outgoing responses. The combined
   ``CsrfMiddleware`` class (which does both) remains for
@@ -85,13 +83,13 @@ Other new features and changes introduced since Django 1.0 include:
 * The ``include()`` function in Django URLconf modules can now accept sequences
   of URL patterns (generated by ``patterns()``) in addition to module names.
 
-* Instances of Django forms (see :ref:`the forms overview <topics-forms-index>`)
+* Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`)
   now have two additional methods, ``hidden_fields()`` and ``visible_fields()``,
   which return the list of hidden -- i.e., ``<input type="hidden">`` -- and
   visible fields on the form, respectively.
 
-* The ``redirect_to`` generic view (see :ref:`the generic views documentation
-  <ref-generic-views>`) now accepts an additional keyword argument
+* The ``redirect_to`` generic view (see :doc:`the generic views documentation
+  </ref/generic-views>`) now accepts an additional keyword argument
   ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP
   permanent redirect (status code 301). If ``False``, the view will emit an HTTP
   temporary redirect (status code 302).
@@ -104,8 +102,8 @@ Other new features and changes introduced since Django 1.0 include:
 
 * The ``{% for %}`` tag in Django's template language now accepts an optional
   ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop
-  over an empty sequence. See :ref:`the list of built-in template tags
-  <ref-templates-builtins>` for examples of this.
+  over an empty sequence. See :doc:`the list of built-in template tags
+  </ref/templates/builtins>` for examples of this.
 
 The Django 1.1 roadmap
 ======================
@@ -153,7 +151,7 @@ discussions there.
 Django's online documentation also includes pointers on how to contribute to
 Django:
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt
index a433efc33c..83423962b3 100644
--- a/docs/releases/1.1-beta-1.txt
+++ b/docs/releases/1.1-beta-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.1-beta-1:
-
 ===============================
 Django 1.1 beta 1 release notes
 ===============================
@@ -22,7 +20,7 @@ What's new in Django 1.1 beta 1
 
 .. seealso::
 
-    The :ref:`1.1 alpha release notes <releases-1.1-alpha-1>`, which has a
+    The :doc:`1.1 alpha release notes </releases/1.1-alpha-1>`, which has a
     list of everything new between Django 1.0 and Django 1.1 alpha.
 
 Model improvements
@@ -71,8 +69,9 @@ processing to convert them to Python objects. If you know you don't need those
 particular fields, you can now tell Django not to retrieve them from the
 database.
 
-You'll do this with the :ref:`new queryset methods <queryset-defer>`
-``defer()`` and ``only()``.
+You'll do this with the new queryset methods
+:meth:`~django.db.models.QuerySet.defer` and
+:meth:`~django.db.models.QuerySet.only`.
 
 New admin features
 ------------------
@@ -90,7 +89,7 @@ up as form widgets on the list pages, and can be edited and saved in bulk.
 Admin "actions"
 ~~~~~~~~~~~~~~~
 
-You can now define :ref:`admin actions <ref-contrib-admin-actions>` that can perform
+You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can perform
 some action to a group of models in bulk. Users will be able to select objects on
 the change list page and then apply these bulk actions to all selected objects.
 
@@ -103,23 +102,23 @@ Testing improvements
 .. currentmodule:: django.test.client
 
 A couple of small but very useful improvements have been made to the
-:ref:`testing framework <topics-testing>`:
+:doc:`testing framework </topics/testing>`:
 
     * The test :class:`Client` now can automatically follow redirects with the
       ``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This
       makes testing views that issue redirects simpler.
-      
+
     * It's now easier to get at the template context in the response returned
       the test client: you'll simply access the context as
       ``request.context[key]``. The old way, which treats ``request.context``
       as a list of contexts, one for each rendered template, is still
       available if you need it.
-      
+
 Conditional view processing
 ---------------------------
 
-Django now has much better support for :ref:`conditional view processing
-<topics-conditional-processing>` using the standard ``ETag`` and
+Django now has much better support for :doc:`conditional view processing
+</topics/conditional-view-processing>` using the standard ``ETag`` and
 ``Last-Modified`` HTTP headers. This means you can now easily short-circuit
 view processing by testing less-expensive conditions. For many views this can
 lead to a serious improvement in speed and reduction in bandwidth.
@@ -133,23 +132,23 @@ release, including:
     * The :djadmin:`dumpdata` management command now accepts individual
       model names as arguments, allowing you to export the data just from
       particular models.
-      
+
     * There's a new :tfilter:`safeseq` template filter which works just like
       :tfilter:`safe` for lists, marking each item in the list as safe.
-      
-    * :ref:`Cache backends <topics-cache>` now support ``incr()`` and
+
+    * :doc:`Cache backends </topics/cache>` now support ``incr()`` and
       ``decr()`` commands to increment and decrement the value of a cache key.
       On cache backends that support atomic increment/decrement -- most
       notably, the memcached backend -- these operations will be atomic, and
       quite fast.
-      
-    * Django now can :ref:`easily delegate authentication to the web server
-      <howto-auth-remote-user>` via a new authentication backend that supports
+
+    * Django now can :doc:`easily delegate authentication to the web server
+      </howto/auth-remote-user>` via a new authentication backend that supports
       the standard ``REMOTE_USER`` environment variable used for this purpose.
-      
+
     * There's a new :func:`django.shortcuts.redirect` function that makes it
       easier to issue redirects given an object, a view name, or a URL.
-      
+
     * The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL
       autocommit <postgresql-notes>`. This is an advanced, PostgreSQL-specific
       feature, that can make certain read-heavy applications a good deal
@@ -183,7 +182,7 @@ central place to search for open issues:
     * http://code.djangoproject.com/timeline
 
 Please open new tickets if no existing ticket corresponds to a problem you're
-running into. 
+running into.
 
 Additionally, discussion of Django development, including progress toward the
 1.1 release, takes place daily on the django-developers mailing list:
@@ -195,9 +194,9 @@ interested in helping out with Django's development, feel free to join the
 discussions there.
 
 Django's online documentation also includes pointers on how to contribute to
-Django: 
+Django:
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.1-rc-1.txt b/docs/releases/1.1-rc-1.txt
index bda424800e..f74444f1f9 100644
--- a/docs/releases/1.1-rc-1.txt
+++ b/docs/releases/1.1-rc-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.1-rc-1:
-
 =============================
 Django 1.1 RC 1 release notes
 =============================
@@ -30,8 +28,8 @@ contains only one new feature (see below); work leading up to this
 release candidate has instead been focused on bugfixing, particularly
 on the new features introduced prior to the 1.1 beta.
 
-For an overview of those features, consult :ref:`the Django 1.1 beta
-release notes <releases-1.1-beta-1>`.
+For an overview of those features, consult :doc:`the Django 1.1 beta
+release notes </releases/1.1-beta-1>`.
 
 
 URL namespaces
@@ -104,7 +102,7 @@ discussions there.
 Django's online documentation also includes pointers on how to contribute to
 Django: 
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.1.2.txt b/docs/releases/1.1.2.txt
index 3e5355f231..90a69759bf 100644
--- a/docs/releases/1.1.2.txt
+++ b/docs/releases/1.1.2.txt
@@ -1,5 +1,3 @@
-.. _releases-1.1.2:
-
 ==========================
 Django 1.1.2 release notes
 ==========================
@@ -15,7 +13,7 @@ improvements. Django 1.1.2 is a recommended upgrade for any
 development or deployment currently using or targeting Django 1.1.
 
 For full details on the new features, backwards incompatibilities, and
-deprecated features in the 1.1 branch, see the :ref:`releases-1.1`.
+deprecated features in the 1.1 branch, see the :doc:`/releases/1.1`.
 
 Backwards-incompatible changes in 1.1.2
 =======================================
diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt
index edb7cf1af2..39cb0ab2b0 100644
--- a/docs/releases/1.1.txt
+++ b/docs/releases/1.1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.1:
-
 ========================
 Django 1.1 release notes
 ========================
@@ -19,7 +17,7 @@ fixes, and an easy upgrade path from Django 1.0.
 Backwards-incompatible changes in 1.1
 =====================================
 
-Django has a policy of :ref:`API stability <misc-api-stability>`. This means
+Django has a policy of :doc:`API stability </misc/api-stability>`. This means
 that, in general, code you develop against Django 1.0 should continue to work
 against 1.1 unchanged. However, we do sometimes make backwards-incompatible
 changes if they're necessary to resolve bugs, and there are a handful of such
@@ -176,7 +174,7 @@ be upgraded to a ``DeprecationWarning``, which will be displayed loudly. Django
 1.3 will remove ``AdminSite.root()`` entirely.
 
 For more details on our deprecation policies and strategy, see
-:ref:`internals-release-process`.
+:doc:`/internals/release-process`.
 
 What's new in Django 1.1
 ========================
@@ -203,8 +201,8 @@ results of the aggregate directly, or else annotate the objects in a
 :class:`QuerySet` with the results of the aggregate query.
 
 This feature is available as new :meth:`QuerySet.aggregate()`` and
-:meth:`QuerySet.annotate()`` methods, and is covered in detail in :ref:`the ORM
-aggregation documentation <topics-db-aggregation>`.
+:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM
+aggregation documentation </topics/db/aggregation>`.
 
 Query expressions
 ~~~~~~~~~~~~~~~~~
@@ -258,21 +256,22 @@ processing to convert them to Python objects. If you know you don't need those
 particular fields, you can now tell Django not to retrieve them from the
 database.
 
-You'll do this with the :ref:`new queryset methods <queryset-defer>`
-``defer()`` and ``only()``.
+You'll do this with the new queryset methods
+:meth:`~django.db.models.QuerySet.defer` and
+:meth:`~django.db.models.QuerySet.only`.
 
 Testing improvements
 --------------------
 
-A few notable improvements have been made to the :ref:`testing framework
-<topics-testing>`.
+A few notable improvements have been made to the :doc:`testing framework
+</topics/testing>`.
 
 Test performance improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. currentmodule:: django.test
 
-Tests written using Django's :ref:`testing framework <topics-testing>` now run
+Tests written using Django's :doc:`testing framework </topics/testing>` now run
 dramatically faster (as much as 10 times faster in many cases).
 
 This was accomplished through the introduction of transaction-based tests: when
@@ -315,7 +314,7 @@ up as form widgets on the list pages, and can be edited and saved in bulk.
 Admin "actions"
 ~~~~~~~~~~~~~~~
 
-You can now define :ref:`admin actions <ref-contrib-admin-actions>` that can
+You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can
 perform some action to a group of models in bulk. Users will be able to select
 objects on the change list page and then apply these bulk actions to all
 selected objects.
@@ -326,8 +325,8 @@ one fell swoop.
 Conditional view processing
 ---------------------------
 
-Django now has much better support for :ref:`conditional view processing
-<topics-conditional-processing>` using the standard ``ETag`` and
+Django now has much better support for :doc:`conditional view processing
+</topics/conditional-view-processing>` using the standard ``ETag`` and
 ``Last-Modified`` HTTP headers. This means you can now easily short-circuit
 view processing by testing less-expensive conditions. For many views this can
 lead to a serious improvement in speed and reduction in bandwidth.
@@ -375,7 +374,7 @@ Other improvements
 
 Other new features and changes introduced since Django 1.0 include:
 
-* The :ref:`CSRF protection middleware <ref-contrib-csrf>` has been split into
+* The :doc:`CSRF protection middleware </ref/contrib/csrf>` has been split into
   two classes -- ``CsrfViewMiddleware`` checks incoming requests, and
   ``CsrfResponseMiddleware`` processes outgoing responses. The combined
   ``CsrfMiddleware`` class (which does both) remains for
@@ -392,13 +391,13 @@ Other new features and changes introduced since Django 1.0 include:
 * The ``include()`` function in Django URLconf modules can now accept sequences
   of URL patterns (generated by ``patterns()``) in addition to module names.
 
-* Instances of Django forms (see :ref:`the forms overview <topics-forms-index>`)
+* Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`)
   now have two additional methods, ``hidden_fields()`` and ``visible_fields()``,
   which return the list of hidden -- i.e., ``<input type="hidden">`` -- and
   visible fields on the form, respectively.
 
-* The ``redirect_to`` generic view (see :ref:`the generic views documentation
-  <ref-generic-views>`) now accepts an additional keyword argument
+* The ``redirect_to`` generic view (see :doc:`the generic views documentation
+  </ref/generic-views>`) now accepts an additional keyword argument
   ``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP
   permanent redirect (status code 301). If ``False``, the view will emit an HTTP
   temporary redirect (status code 302).
@@ -411,8 +410,8 @@ Other new features and changes introduced since Django 1.0 include:
 
 * The ``{% for %}`` tag in Django's template language now accepts an optional
   ``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop
-  over an empty sequence. See :ref:`the list of built-in template tags
-  <ref-templates-builtins>` for examples of this.
+  over an empty sequence. See :doc:`the list of built-in template tags
+  </ref/templates/builtins>` for examples of this.
 
 * The :djadmin:`dumpdata` management command now accepts individual
   model names as arguments, allowing you to export the data just from
@@ -421,14 +420,14 @@ Other new features and changes introduced since Django 1.0 include:
 * There's a new :tfilter:`safeseq` template filter which works just like
   :tfilter:`safe` for lists, marking each item in the list as safe.
 
-* :ref:`Cache backends <topics-cache>` now support ``incr()`` and
+* :doc:`Cache backends </topics/cache>` now support ``incr()`` and
   ``decr()`` commands to increment and decrement the value of a cache key.
   On cache backends that support atomic increment/decrement -- most
   notably, the memcached backend -- these operations will be atomic, and
   quite fast.
 
-* Django now can :ref:`easily delegate authentication to the web server
-  <howto-auth-remote-user>` via a new authentication backend that supports
+* Django now can :doc:`easily delegate authentication to the web server
+  </howto/auth-remote-user>` via a new authentication backend that supports
   the standard ``REMOTE_USER`` environment variable used for this purpose.
 
 * There's a new :func:`django.shortcuts.redirect` function that makes it
@@ -455,7 +454,7 @@ join the discussions!
 Django's online documentation also includes pointers on how to contribute to
 Django:
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.2-alpha-1.txt b/docs/releases/1.2-alpha-1.txt
index 1e9d4422ce..4144a9a3a9 100644
--- a/docs/releases/1.2-alpha-1.txt
+++ b/docs/releases/1.2-alpha-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.2-alpha-1:
-
 ================================
 Django 1.2 alpha 1 release notes
 ================================
@@ -25,7 +23,7 @@ CSRF Protection
 ---------------
 
 There have been large changes to the way that CSRF protection works, detailed in
-:ref:`the CSRF documentaton <ref-contrib-csrf>`.  The following are the major
+:doc:`the CSRF documentaton </ref/contrib/csrf>`.  The following are the major
 changes that developers must be aware of:
 
  * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and
@@ -303,7 +301,7 @@ User Messages API
 
 The API for storing messages in the user ``Message`` model (via
 ``user.message_set.create``) is now deprecated and will be removed in Django
-1.4 according to the standard :ref:`release process <internals-release-process>`.
+1.4 according to the standard :doc:`release process </internals/release-process>`.
 
 To upgrade your code, you need to replace any instances of::
 
@@ -327,7 +325,7 @@ with::
         ...
 
 For more information, see the full
-:ref:`messages documentation <ref-contrib-messages>`. You should begin to
+:doc:`messages documentation </ref/contrib/messages>`. You should begin to
 update your code to use the new API immediately.
 
 Date format helper functions
@@ -378,8 +376,8 @@ release cycle. Some minor features will continue development until the
 CSRF support
 ------------
 
-Django now has much improved protection against :ref:`Cross-Site
-Request Forgery (CSRF) attacks<ref-contrib-csrf>`. This type of attack
+Django now has much improved protection against :doc:`Cross-Site
+Request Forgery (CSRF) attacks</ref/contrib/csrf>`. 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
@@ -395,7 +393,7 @@ You can now :ref:`configure the way that Django sends e-mail
 can now choose a configurable e-mail backend to send messages. If your
 hosting provider uses a sandbox or some other non-SMTP technique for
 sending mail, you can now construct an e-mail backend that will allow
-Django's standard :ref:`mail sending methods<topics-email>` to use
+Django's standard :doc:`mail sending methods</topics/email>` to use
 those facilities.
 
 This also makes it easier to debug mail sending - Django ships with
@@ -408,8 +406,8 @@ e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.
 Messages Framework
 ------------------
 
-Django now includes a robust and configurable :ref:`messages framework
-<ref-contrib-messages>` with built-in support for cookie- and session-based
+Django now includes a robust and configurable :doc:`messages framework
+</ref/contrib/messages>` with built-in support for cookie- and session-based
 messaging, for both anonymous and authenticated clients. The messages framework
 replaces the deprecated user message API and allows you to temporarily store
 messages in one request and retrieve them for display in a subsequent request
@@ -418,8 +416,8 @@ messages in one request and retrieve them for display in a subsequent request
 Support for multiple databases
 ------------------------------
 
-Django 1.2 adds the ability to use :ref:`more than one database
-<topics-db-multi-db>` in your Django project. Queries can be
+Django 1.2 adds the ability to use :doc:`more than one database
+</topics/db/multi-db>` in your Django project. Queries can be
 issued at a specific database with the `using()` method on
 querysets; individual objects can be saved to a specific database
 by providing a ``using`` argument when you save the instance.
@@ -500,7 +498,7 @@ from the test run that reports details of the tests run before the interruption.
 Improved localization
 ---------------------
 
-Django's :ref:`internationalization framework <topics-i18n>` has been
+Django's :doc:`internationalization framework </topics/i18n/index>` has been
 expanded by locale aware formatting and form processing. That means, if
 enabled, dates and numbers on templates will be displayed using the format
 specified for the current locale. Django will also use localized formats
@@ -568,7 +566,7 @@ discussions there.
 Django's online documentation also includes pointers on how to contribute to
 Django:
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.2-beta-1.txt b/docs/releases/1.2-beta-1.txt
index 650971de2b..2a12ef33bb 100644
--- a/docs/releases/1.2-beta-1.txt
+++ b/docs/releases/1.2-beta-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.2-beta-1:
-
 ===============================
 Django 1.2 beta 1 release notes
 ===============================
@@ -19,7 +17,7 @@ As such, this release is *not* intended for production use, and any
 such use is discouraged.
 
 This document covers changes since the Django 1.2 alpha release; the
-:ref:`1.2 alpha release notes <releases-1.2-alpha-1>` cover new and
+:doc:`1.2 alpha release notes </releases/1.2-alpha-1>` cover new and
 updated features in Django between 1.1 and 1.2 alpha.
 
 
@@ -28,7 +26,7 @@ Deprecations and other changes in 1.2 beta
 
 This beta release deprecates two portions of public API, and
 introduces a potentially backwards-incompatible change to
-another. Under :ref:`our API stability policy <misc-api-stability>`,
+another. Under :doc:`our API stability policy </misc/api-stability>`,
 deprecation proceeds over multiple release cycles: initially, the
 deprecated API will raise ``PendingDeprecationWarning``, followed by
 raising ``DeprecationWarning`` in the next release, and finally
@@ -58,8 +56,8 @@ Also, in accordance with `RSS best practices`_, RSS feeds will now
 include an ``atom:link`` element. You may need to update your tests to
 take this into account.
 
-For more information, see the full :ref:`syndication framework
-documentation <ref-contrib-syndication>`.
+For more information, see the full :doc:`syndication framework
+documentation </ref/contrib/syndication>`.
 
 .. _RSS best practices: http://www.rssboard.org/rss-profile
 
@@ -93,7 +91,7 @@ added in Django 1.2 alpha but not documented with the alpha release.
 
 The default authentication backends shipped with Django do not
 currently make use of this, but third-party authentication backends
-are free to do so. See the :ref:`authentication docs <topics-auth>`
+are free to do so. See the :doc:`authentication docs </topics/auth>`
 for more information.
 
 
@@ -106,7 +104,7 @@ class will check the backend for permissions, just as the normal
 ``User`` does. This is intended to help centralize permission
 handling; apps can always delegate the question of whether something
 is allowed or not to the authorization/authentication system. See the
-:ref:`authentication docs <topics-auth>` for more details.
+:doc:`authentication docs </topics/auth>` for more details.
 
 
 ``select_related()`` improvements
@@ -163,7 +161,7 @@ discussions there.
 Django's online documentation also includes pointers on how to
 contribute to Django:
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation
 or simply triaging tickets and helping to test proposed bugfixes --
diff --git a/docs/releases/1.2-rc-1.txt b/docs/releases/1.2-rc-1.txt
index c627612a6e..b599dcca1e 100644
--- a/docs/releases/1.2-rc-1.txt
+++ b/docs/releases/1.2-rc-1.txt
@@ -1,5 +1,3 @@
-.. _releases-1.2-rc-1:
-
 =============================
 Django 1.2 RC 1 release notes
 =============================
@@ -21,8 +19,8 @@ such use is discouraged.
 
 Django has been feature frozen since the 1.2 beta release, so this
 release candidate contains no new features, only bugfixes; for a
-summary of features new to Django 1.2, consult the :ref:`1.2 alpha
-<releases-1.2-alpha-1>` and :ref:`1.2 beta <releases-1.2-beta-1>`
+summary of features new to Django 1.2, consult the :doc:`1.2 alpha
+</releases/1.2-alpha-1>` and :doc:`1.2 beta </releases/1.2-beta-1>`
 release notes.
 
 
@@ -42,7 +40,7 @@ This change should affect only a small number of Django users, as most
 operating-system vendors today are shipping Python 2.4 or newer as
 their default version. If you're still using Python 2.3, however,
 you'll need to stick to Django 1.1 until you can upgrade; per
-:ref:`our support policy <internals-release-process>`, Django 1.1 will
+:doc:`our support policy </internals/release-process>`, Django 1.1 will
 continue to receive security support until the release of Django 1.3.
 
 A roadmap for Django's overall 2.x Python support, and eventual
@@ -96,7 +94,7 @@ discussions there.
 Django's online documentation also includes pointers on how to contribute to
 Django: 
 
-    * :ref:`How to contribute to Django <internals-contributing>`
+    * :doc:`How to contribute to Django </internals/contributing>`
 
 Contributions on any level -- developing code, writing documentation or simply
 triaging tickets and helping to test proposed bugfixes -- are always welcome and
diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt
index a54675514f..f46c19b8e8 100644
--- a/docs/releases/1.2.txt
+++ b/docs/releases/1.2.txt
@@ -1,5 +1,3 @@
-.. _releases-1.2:
-
 ========================
 Django 1.2 release notes
 ========================
@@ -21,11 +19,11 @@ Overview
 Django 1.2 introduces several large, important new features, including:
 
     * Support for `multiple database connections`_ in a single Django instance.
-    
+
     * `Model validation`_ inspired by Django's form validation.
-    
+
     * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF).
-    
+
     * A new `user "messages" framework`_ with support for cookie- and session-based
       message for both anonymous and authenticated users.
 
@@ -49,13 +47,13 @@ be found below`_.
 
 .. seealso::
 
-    `Django Advent`_ covered the release of Django 1.2 with a series of 
+    `Django Advent`_ covered the release of Django 1.2 with a series of
     articles and tutorials that cover some of the new features in depth.
-        
+
 .. _django advent: http://djangoadvent.com/
 
 Wherever possible these features have been introduced in a backwards-compatible
-manner per :ref:`our API stability policy <misc-api-stability>` policy.
+manner per :doc:`our API stability policy </misc/api-stability>` policy.
 
 However, a handful of features *have* changed in ways that, for some users, will be
 backwards-incompatible. The big changes are:
@@ -66,7 +64,7 @@ backwards-incompatible. The big changes are:
     * The new CSRF protection framework is not backwards-compatible with
       the old system. Users of the old system will not be affected until
       the old system is removed in Django 1.4.
-      
+
       However, upgrading to the new CSRF protection framework requires a few
       important backwards-incompatible changes, detailed in `CSRF Protection`_,
       below.
@@ -74,12 +72,12 @@ backwards-incompatible. The big changes are:
     * Authors of custom :class:`~django.db.models.Field` subclasses should be
       aware that a number of methods have had a change in prototype, detailed
       under `get_db_prep_*() methods on Field`_, below.
-      
+
     * The internals of template tags have changed somewhat; authors of custom
       template tags that need to store state (e.g. custom control flow tags)
       should ensure that their code follows the new rules for `stateful template
       tags`_
-    
+
     * The :func:`~django.contrib.auth.decorators.user_passes_test`,
       :func:`~django.contrib.auth.decorators.login_required`, and
       :func:`~django.contrib.auth.decorators.permission_required`, decorators
@@ -110,7 +108,7 @@ This change should affect only a small number of Django users, as most
 operating-system vendors today are shipping Python 2.4 or newer as
 their default version. If you're still using Python 2.3, however,
 you'll need to stick to Django 1.1 until you can upgrade; per
-:ref:`our support policy <internals-release-process>`, Django 1.1 will
+:doc:`our support policy </internals/release-process>`, Django 1.1 will
 continue to receive security support until the release of Django 1.3.
 
 A roadmap for Django's overall 2.x Python support, and eventual
@@ -123,8 +121,8 @@ What's new in Django 1.2
 Support for multiple databases
 ------------------------------
 
-Django 1.2 adds the ability to use :ref:`more than one database
-<topics-db-multi-db>` in your Django project. Queries can be issued at a
+Django 1.2 adds the ability to use :doc:`more than one database
+</topics/db/multi-db>` in your Django project. Queries can be issued at a
 specific database with the `using()` method on ``QuerySet`` objects. Individual
 objects can be saved to a specific database by providing a ``using`` argument
 when you call ``save()``.
@@ -134,7 +132,7 @@ Model validation
 
 Model instances now have support for :ref:`validating their own data
 <validating-objects>`, and both model and form fields now accept configurable
-lists of :ref:`validators <ref-validators>` specifying reusable, encapsulated
+lists of :doc:`validators </ref/validators>` specifying reusable, encapsulated
 validation behavior. Note, however, that validation must still be performed
 explicitly. Simply invoking a model instance's ``save()`` method will not
 perform any validation of the instance's data.
@@ -142,8 +140,8 @@ perform any validation of the instance's data.
 Improved CSRF protection
 ------------------------
 
-Django now has much improved protection against :ref:`Cross-Site Request Forgery
-(CSRF) attacks<ref-contrib-csrf>`. This type of attack occurs when a malicious
+Django now has much improved protection against :doc:`Cross-Site Request Forgery
+(CSRF) attacks</ref/contrib/csrf>`. 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
@@ -153,8 +151,8 @@ with someone else's credentials, is also covered.
 Messages framework
 ------------------
 
-Django now includes a robust and configurable :ref:`messages framework
-<ref-contrib-messages>` with built-in support for cookie- and session-based
+Django now includes a robust and configurable :doc:`messages framework
+</ref/contrib/messages>` with built-in support for cookie- and session-based
 messaging, for both anonymous and authenticated clients. The messages framework
 replaces the deprecated user message API and allows you to temporarily store
 messages in one request and retrieve them for display in a subsequent request
@@ -166,8 +164,8 @@ Object-level permissions
 A foundation for specifying permissions at the per-object level has been added.
 Although there is no implementation of this in core, a custom authentication
 backend can provide this implementation and it will be used by
-:class:`django.contrib.auth.models.User`. See the :ref:`authentication docs
-<topics-auth>` for more information.
+:class:`django.contrib.auth.models.User`. See the :doc:`authentication docs
+</topics/auth>` for more information.
 
 Permissions for anonymous users
 -------------------------------
@@ -176,8 +174,8 @@ If you provide a custom auth backend with ``supports_anonymous_user`` set to
 ``True``, AnonymousUser will check the backend for permissions, just like
 User already did.  This is useful for centralizing permission handling - apps
 can always delegate the question of whether something is allowed or not to
-the authorization/authentication backend. See the :ref:`authentication
-docs <topics-auth>` for more details.
+the authorization/authentication backend. See the :doc:`authentication
+docs </topics/auth>` for more details.
 
 Relaxed requirements for usernames
 ----------------------------------
@@ -194,7 +192,7 @@ You can now :ref:`configure the way that Django sends e-mail
 can now choose a configurable e-mail backend to send messages. If your
 hosting provider uses a sandbox or some other non-SMTP technique for
 sending mail, you can now construct an e-mail backend that will allow
-Django's standard :ref:`mail sending methods<topics-email>` to use
+Django's standard :doc:`mail sending methods</topics/email>` to use
 those facilities.
 
 This also makes it easier to debug mail sending. Django ships with
@@ -286,7 +284,7 @@ Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type.
 Improved localization
 ---------------------
 
-Django's :ref:`internationalization framework <topics-i18n>` has been expanded
+Django's :doc:`internationalization framework </topics/i18n/index>` has been expanded
 with locale-aware formatting and form processing. That means, if enabled, dates
 and numbers on templates will be displayed using the format specified for the
 current locale. Django will also use localized formats when parsing data in
@@ -309,8 +307,8 @@ the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting
 Syndication feeds as views
 --------------------------
 
-:ref:`Syndication feeds <ref-contrib-syndication>` can now be used directly as
-views in your :ref:`URLconf <topics-http-urls>`. This means that you can
+:doc:`Syndication feeds </ref/contrib/syndication>` can now be used directly as
+views in your :doc:`URLconf </topics/http/urls>`. This means that you can
 maintain complete control over the URL structure of your feeds. Like any other
 view, feeds views are passed a ``request`` object, so you can do anything you
 would normally do with a view, like user based access control, or making a feed
@@ -319,7 +317,7 @@ a named URL.
 GeoDjango
 ---------
 
-The most significant new feature for :ref:`GeoDjango <ref-contrib-gis>`
+The most significant new feature for :doc:`GeoDjango </ref/contrib/gis/index>`
 in 1.2 is support for multiple spatial databases.  As a result,
 the following :ref:`spatial database backends <spatial-backends>`
 are now included:
@@ -357,7 +355,7 @@ set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on
 the features returned when iterating over a
 :class:`~django.contrib.gis.gdal.Layer`.
 
-Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now
+Finally, :doc:`GeoDjango's documentation </ref/contrib/gis/index>` is now
 included with Django's and is no longer
 hosted separately at `geodjango.org <http://geodjango.org/>`_.
 
@@ -391,8 +389,8 @@ Backwards-incompatible changes in 1.2
 =====================================
 
 Wherever possible the new features above have been introduced in a
-backwards-compatible manner per :ref:`our API stability policy
-<misc-api-stability>` policy. This means that practically all existing
+backwards-compatible manner per :doc:`our API stability policy
+</misc/api-stability>` policy. This means that practically all existing
 code which worked with Django 1.1 will continue to work with Django
 1.2; such code will, however, begin issuing warnings (see below for
 details).
@@ -405,7 +403,7 @@ CSRF Protection
 ---------------
 
 We've made large changes to the way CSRF protection works, detailed in
-:ref:`the CSRF documentaton <ref-contrib-csrf>`. Here are the major changes you
+:doc:`the CSRF documentaton </ref/contrib/csrf>`. Here are the major changes you
 should be aware of:
 
  * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated and
@@ -435,6 +433,8 @@ database-compatible values. A custom field might look something like::
 
     class CustomModelField(models.Field):
         # ...
+        def db_type(self):
+            # ...
 
         def get_db_prep_save(self, value):
             # ...
@@ -451,6 +451,9 @@ two extra methods have been introduced::
     class CustomModelField(models.Field):
         # ...
 
+        def db_type(self, connection):
+            # ...
+
         def get_prep_value(self, value):
             # ...
 
@@ -467,10 +470,10 @@ two extra methods have been introduced::
             # ...
 
 These changes are required to support multiple databases --
-``get_db_prep_*`` can no longer make any assumptions regarding the
-database for which it is preparing. The ``connection`` argument now
-provides the preparation methods with the specific connection for
-which the value is being prepared.
+``db_type`` and ``get_db_prep_*`` can no longer make any assumptions
+regarding the database for which it is preparing. The ``connection``
+argument now provides the preparation methods with the specific
+connection for which the value is being prepared.
 
 The two new methods exist to differentiate general data-preparation
 requirements from requirements that are database-specific. The
@@ -603,13 +606,13 @@ new keyword and so is not a valid variable name in this tag.
 --------------
 
 ``LazyObject`` is an undocumented-but-often-used utility class used for lazily
-wrapping other objects of unknown type. 
+wrapping other objects of unknown type.
 
 In Django 1.1 and earlier, it handled introspection in a non-standard way,
 depending on wrapped objects implementing a public method named
 ``get_all_members()``. Since this could easily lead to name clashes, it has been
 changed to use the standard Python introspection method, involving
-``__members__`` and ``__dir__()``. 
+``__members__`` and ``__dir__()``.
 
 If you used ``LazyObject`` in your own code
 and implemented the ``get_all_members()`` method for wrapped objects, you'll need
@@ -737,9 +740,9 @@ be removed entirely.
 
 .. seealso::
 
-    For more details, see the documentation :ref:`Django's release process
-    <internals-release-process>` and our :ref:`deprecation timeline
-    <internals-deprecation>`.`
+    For more details, see the documentation :doc:`Django's release process
+    </internals/release-process>` and our :doc:`deprecation timeline
+    </internals/deprecation>`.`
 
 .. _specifying-databases:
 
@@ -872,7 +875,7 @@ User Messages API
 
 The API for storing messages in the user ``Message`` model (via
 ``user.message_set.create``) is now deprecated and will be removed in Django
-1.4 according to the standard :ref:`release process <internals-release-process>`.
+1.4 according to the standard :doc:`release process </internals/release-process>`.
 
 To upgrade your code, you need to replace any instances of this::
 
@@ -896,7 +899,7 @@ following::
         ...
 
 For more information, see the full
-:ref:`messages documentation <ref-contrib-messages>`. You should begin to
+:doc:`messages documentation </ref/contrib/messages>`. You should begin to
 update your code to use the new API immediately.
 
 Date format helper functions
@@ -960,7 +963,7 @@ Django 1.4.
 
 The new class has an almost identical API, but allows instances to be
 used as views. For example, consider the use of the old framework in
-the following :ref:`URLconf <topics-http-urls>`::
+the following :doc:`URLconf </topics/http/urls>`::
 
     from django.conf.urls.defaults import *
     from myproject.feeds import LatestEntries, LatestEntriesByCategory
@@ -1029,8 +1032,8 @@ In accordance with `RSS best practices`_, RSS feeds will now include
 an ``atom:link`` element. You may need to update your tests to take
 this into account.
 
-For more information, see the full :ref:`syndication framework
-documentation <ref-contrib-syndication>`.
+For more information, see the full :doc:`syndication framework
+documentation </ref/contrib/syndication>`.
 
 .. _RSS best practices: http://www.rssboard.org/rss-profile
 
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
new file mode 100644
index 0000000000..51de6fdd92
--- /dev/null
+++ b/docs/releases/1.3.txt
@@ -0,0 +1,86 @@
+============================================
+Django 1.3 release notes - UNDER DEVELOPMENT
+============================================
+
+This page documents release notes for the as-yet-unreleased Django
+1.3. As such, it's tentative and subject to change. It provides
+up-to-date information for those who are following trunk.
+
+Django 1.3 includes a number of nifty `new features`_, lots of bug
+fixes and an easy upgrade path from Django 1.2.
+
+.. _new features: `What's new in Django 1.3`_
+
+.. _backwards-incompatible-changes-1.3:
+
+Backwards-incompatible changes in 1.3
+=====================================
+
+PasswordInput default rendering behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prior to Django 1.3, a :class:`~django.forms.PasswordInput` would render
+data values like any other form. If a form submission raised an error,
+the password that was submitted would be reflected to the client as form
+data populating the form for resubmission.
+
+This had the potential to leak passwords, as any failed password
+attempt would cause the password that was typed to be sent back to the
+client.
+
+In Django 1.3, the default behavior of
+:class:`~django.forms.PasswordInput` is to suppress the display of
+password values. This change doesn't alter the way form data is
+validated or handled. It only affects the user experience with
+passwords on a form when they make an error submitting form data (such
+as on unsuccessful logins, or when completing a registration form).
+
+If you want restore the pre-Django 1.3 behavior, you need to pass in a
+custom widget to your form that sets the ``render_value`` argument::
+
+    class LoginForm(forms.Form):
+        username = forms.CharField(max_length=100)
+        password = forms.PasswordField(widget=forms.PasswordInput(render_value=True))
+
+.. _deprecated-features-1.3:
+
+Features deprecated in 1.3
+==========================
+
+Django 1.3 deprecates some features from earlier releases.
+These features are still supported, but will be gradually phased out
+over the next few release cycles.
+
+Code taking advantage of any of the features below will raise a
+``PendingDeprecationWarning`` in Django 1.3. This warning will be
+silent by default, but may be turned on using Python's `warnings
+module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
+
+.. _warnings module: http://docs.python.org/library/warnings.html
+
+In Django 1.4, these warnings will become a ``DeprecationWarning``,
+which is *not* silent. In Django 1.5 support for these features will
+be removed entirely.
+
+.. seealso::
+
+    For more details, see the documentation :doc:`Django's release process
+    </internals/release-process>` and our :doc:`deprecation timeline
+    </internals/deprecation>`.`
+
+``mod_python`` support
+~~~~~~~~~~~~~~~~~~~~~~
+
+The ``mod_python`` library has not had a release since 2007 or a commit since
+2008. The Apache Foundation board voted to remove ``mod_python`` from the set
+of active projects in its version control repositories, and its lead developer
+has shifted all of his efforts toward the lighter, slimmer, more stable, and
+more flexible ``mod_wsgi`` backend.
+
+If you are currently using the ``mod_python`` request handler, it is strongly
+encouraged you redeploy your Django instances using :doc:`mod_wsgi
+</howto/deployment/modwsgi>`.
+
+What's new in Django 1.3
+========================
+
diff --git a/docs/releases/index.txt b/docs/releases/index.txt
index 676ee67519..aa014f3cf2 100644
--- a/docs/releases/index.txt
+++ b/docs/releases/index.txt
@@ -1,5 +1,3 @@
-.. _releases-index:
-
 =============
 Release notes
 =============
@@ -16,6 +14,13 @@ up to and including the new version.
 Final releases
 ==============
 
+1.3 release
+-----------
+.. toctree::
+   :maxdepth: 1
+
+   1.3
+
 1.2 release
 -----------
 .. toctree::