Fixed #14141: docs now use the :doc: construct for links between documents.

Thanks, Ramiro Morales.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13608 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/_ext/djangodocs.py

@@ -78,11 +78,11 @@ class VersionDirective(Directive):
         ret.append(node)
         if not is_nextversion:
             if len(self.arguments) == 1:
-                linktext = 'Please, see the release notes <releases-%s>' % (arg0)
+                linktext = 'Please, see the release notes </releases/%s>' % (arg0)
                 try:
-                    xrefs = roles.XRefRole()('std:ref', linktext, linktext, self.lineno, self.state) # Sphinx >= 1.0
+                    xrefs = roles.XRefRole()('doc', linktext, linktext, self.lineno, self.state) # Sphinx >= 1.0
                 except AttributeError:
-                    xrefs = roles.xfileref_role('ref', linktext, linktext, self.lineno, self.state) # Sphinx < 1.0
+                    xrefs = roles.xfileref_role('doc', linktext, linktext, self.lineno, self.state) # Sphinx < 1.0
                 node.extend(xrefs[0])
             node['version'] = arg0
         else:

docs/faq/admin.txt

@@ -1,5 +1,3 @@
-.. _faq-admin:
-
 FAQ: The admin
 ==============
 
@@ -32,7 +30,7 @@ How can I prevent the cache middleware from caching the admin site?
 -------------------------------------------------------------------
 
 Set the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting to ``True``. See the
-:ref:`cache documentation <topics-cache>` for more information.
+:doc:`cache documentation </topics/cache>` for more information.
 
 How do I automatically set a field's value to the user who last edited the object in the admin?
 -----------------------------------------------------------------------------------------------
@@ -91,5 +89,5 @@ We like it, but if you don't agree, you can modify the admin site's
 presentation by editing the CSS stylesheet and/or associated image files. The
 site is built using semantic HTML and plenty of CSS hooks, so any changes you'd
 like to make should be possible by editing the stylesheet. We've got a
-:ref:`guide to the CSS used in the admin <obsolete-admin-css>` to get you started.
+:doc:`guide to the CSS used in the admin </obsolete/admin-css>` to get you started.
 

docs/faq/contributing.txt

@@ -1,5 +1,3 @@
-.. _faq-contributing:
-
 FAQ: Contributing code
 ======================
 
@@ -7,7 +5,7 @@ How can I get started contributing code to Django?
 --------------------------------------------------
 
 Thanks for asking! We've written an entire document devoted to this question.
-It's titled :ref:`Contributing to Django <internals-contributing>`.
+It's titled :doc:`Contributing to Django </internals/contributing>`.
 
 I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch?
 --------------------------------------------------------------------------------------------

docs/faq/general.txt

@@ -1,5 +1,3 @@
-.. _faq-general:
-
 FAQ: General
 ============
 
@@ -63,15 +61,15 @@ at any level -- database servers, caching servers or Web/application servers.
 
 The framework cleanly separates components such as its database layer and
 application layer. And it ships with a simple-yet-powerful
-:ref:`cache framework <topics-cache>`.
+:doc:`cache framework </topics/cache>`.
 
 Who's behind this?
 ------------------
 
 Django was originally developed at World Online, the Web department of a
 newspaper in Lawrence, Kansas, USA. Django's now run by an international team of
-volunteers; you can read all about them over at the :ref:`list of committers
-<internals-committers>`
+volunteers; you can read all about them over at the :doc:`list of committers
+</internals/committers>`
 
 Which sites use Django?
 -----------------------
@@ -146,7 +144,7 @@ philosophies 100%.
 Like we said: We're picky.
 
 We've documented our philosophies on the
-:ref:`design philosophies page <misc-design-philosophies>`.
+:doc:`design philosophies page </misc/design-philosophies>`.
 
 Is Django a content-management-system (CMS)?
 --------------------------------------------

docs/faq/help.txt

@@ -1,5 +1,3 @@
-.. _faq-help:
-
 FAQ: Getting Help
 =================
 

docs/faq/index.txt

@@ -1,5 +1,3 @@
-.. _faq-index:
-
 ==========
 Django FAQ
 ==========

docs/faq/install.txt

@@ -1,5 +1,3 @@
-.. _faq-install:
-
 FAQ: Installation
 =================
 
@@ -7,9 +5,9 @@ How do I get started?
 ---------------------
 
     #. `Download the code`_.
-    #. Install Django (read the :ref:`installation guide <intro-install>`).
-    #. Walk through the :ref:`tutorial <intro-tutorial01>`.
-    #. Check out the rest of the :ref:`documentation <index>`, and `ask questions`_ if you
+    #. Install Django (read the :doc:`installation guide </intro/install>`).
+    #. Walk through the :doc:`tutorial </intro/tutorial01>`.
+    #. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you
        run into trouble.
 
 .. _`Download the code`: http://www.djangoproject.com/download/
@@ -26,7 +24,7 @@ For a development environment -- if you just want to experiment with Django --
 you don't need to have a separate Web server installed; Django comes with its
 own lightweight development server. For a production environment, Django
 follows the WSGI_ spec, which means it can run on a variety of server
-platforms.  See :ref:`Deploying Django <howto-deployment-index>` for some
+platforms.  See :doc:`Deploying Django </howto/deployment/index>` for some
 popular alternatives.  Also, the `server arrangements wiki page`_ contains
 details for several deployment strategies.
 

docs/faq/models.txt

@@ -1,5 +1,3 @@
-.. _faq-models:
-
 FAQ: Databases and models
 =========================
 
@@ -30,7 +28,7 @@ backend, and not all backends provide a way to retrieve the SQL after quoting.
 
 .. versionadded:: 1.2
 
-If you are using :ref:`multiple databases<topics-db-multi-db>`, you can use the
+If you are using :doc:`multiple databases</topics/db/multi-db>`, you can use the
 same interface on each member of the ``connections`` dictionary::
 
     >>> from django.db import connections
@@ -39,7 +37,7 @@ same interface on each member of the ``connections`` dictionary::
 Can I use Django with a pre-existing database?
 ----------------------------------------------
 
-Yes. See :ref:`Integrating with a legacy database <howto-legacy-databases>`.
+Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
 
 If I make changes to a model, how do I update the database?
 -----------------------------------------------------------

docs/faq/usage.txt

@@ -1,5 +1,3 @@
-.. _faq-usage:
-
 FAQ: Using Django
 =================
 

docs/glossary.txt

@@ -9,19 +9,19 @@ Glossary
     field
         An attribute on a :term:`model`; a given field usually maps directly to
         a single database column.
-        
-        See :ref:`topics-db-models`.
+
+        See :doc:`/topics/db/models`.
 
     generic view
         A higher-order :term:`view` function that provides an abstract/generic
         implementation of a common idiom or pattern found in view development.
-        
-        See :ref:`ref-generic-views`.
+
+        See :doc:`/ref/generic-views`.
 
     model
         Models store your application's data.
-        
-        See :ref:`topics-db-models`.
+
+        See :doc:`/topics/db/models`.
 
     MTV
         See :ref:`mtv`.
@@ -41,7 +41,7 @@ Glossary
     property
         Also known as "managed attributes", and a feature of Python since
         version 2.2. From `the property documentation`__:
-        
+
             Properties are a neat way to implement attributes whose usage
             resembles attribute access, but whose implementation uses method
             calls. [...] You
@@ -56,26 +56,26 @@ Glossary
 
     queryset
         An object representing some set of rows to be fetched from the database.
-        
-        See :ref:`topics-db-queries`.
+
+        See :doc:`/topics/db/queries`.
 
     slug
         A short label for something, containing only letters, numbers,
         underscores or hyphens. They're generally used in URLs. For
         example, in a typical blog entry URL:
-        
+
         .. parsed-literal::
-        
+
             http://www.djangoproject.com/weblog/2008/apr/12/**spring**/
-            
+
         the last bit (``spring``) is the slug.
 
     template
         A chunk of text that acts as formatting for representing data. A
         template helps to abstract the presentation of data from the data
         itself.
-        
-        See :ref:`topics-templates`.
-        
+
+        See :doc:`/topics/templates`.
+
     view
-        A function responsible for rending a page.
+        A function responsible for rending a page.

docs/howto/apache-auth.txt

@@ -1,12 +1,10 @@
-.. _howto-apache-auth:
-
 =========================================================
 Authenticating against Django's user database from Apache
 =========================================================
 
 Since keeping multiple authentication databases in sync is a common problem when
 dealing with Apache, you can configuring Apache to authenticate against Django's
-:ref:`authentication system <topics-auth>` directly. For example, you
+:doc:`authentication system </topics/auth>` directly. For example, you
 could:
 
     * Serve static/media files directly from Apache only to authenticated users.

docs/howto/auth-remote-user.txt

@@ -1,5 +1,3 @@
-.. _howto-auth-remote-user:
-
 ====================================
 Authentication using ``REMOTE_USER``
 ====================================

docs/howto/custom-file-storage.txt

@@ -1,5 +1,3 @@
-.. _howto-custom-file-storage:
-
 Writing a custom storage system
 ===============================
 
@@ -37,7 +35,7 @@ You'll need to follow these steps:
    the ``path()`` method.
 
 Your custom storage system may override any of the storage methods explained in
-:ref:`ref-files-storage`, but you **must** implement the following methods:
+:doc:`/ref/files/storage`, but you **must** implement the following methods:
 
     * :meth:`Storage.delete`
     * :meth:`Storage.exists`
@@ -63,7 +61,7 @@ backend storage system.
 
 Called by ``Storage.save()``. The ``name`` will already have gone through
 ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a
-``File`` object itself. 
+``File`` object itself.
 
 Should return the actual name of name of the file saved (usually the ``name``
 passed in, but if the storage needs to change the file name return the new name

docs/howto/custom-management-commands.txt

@@ -1,5 +1,3 @@
-.. _howto-custom-management-commands:
-
 ====================================
 Writing custom django-admin commands
 ====================================
@@ -10,7 +8,7 @@ Applications can register their own actions with ``manage.py``. For example,
 you might want to add a ``manage.py`` action for a Django app that you're
 distributing. In this document, we will be building a custom ``closepoll``
 command for the ``polls`` application from the
-:ref:`tutorial<intro-tutorial01>`.
+:doc:`tutorial</intro/tutorial01>`.
 
 To do this, just add a ``management/commands`` directory to the application.
 Each Python module in that directory will be auto-discovered and registered as
@@ -77,7 +75,7 @@ The new custom command can be called using ``python manage.py closepoll
 The ``handle()`` method takes zero or more ``poll_ids`` and sets ``poll.opened``
 to ``False`` for each one. If the user referenced any nonexistant polls, a
 :class:`CommandError` is raised. The ``poll.opened`` attribute does not exist
-in the :ref:`tutorial<intro-tutorial01>` and was added to
+in the :doc:`tutorial</intro/tutorial01>` and was added to
 ``polls.models.Poll`` for this example.
 
 The same ``closepoll`` could be easily modified to delete a given poll instead
@@ -99,7 +97,7 @@ must be added to :attr:`~BaseCommand.option_list` like this:
         # ...
 
 In addition to being able to add custom command line options, all
-:ref:`management commands<ref-django-admin>` can accept some
+:doc:`management commands</ref/django-admin>` can accept some
 default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
 
 Command objects

docs/howto/custom-model-fields.txt

@@ -1,5 +1,3 @@
-.. _howto-custom-model-fields:
-
 ===========================
 Writing custom model fields
 ===========================
@@ -10,7 +8,7 @@ Writing custom model fields
 Introduction
 ============
 
-The :ref:`model reference <topics-db-models>` documentation explains how to use
+The :doc:`model reference </topics/db/models>` documentation explains how to use
 Django's standard field classes -- :class:`~django.db.models.CharField`,
 :class:`~django.db.models.DateField`, etc. For many purposes, those classes are
 all you'll need. Sometimes, though, the Django version won't meet your precise
@@ -109,7 +107,7 @@ What does a field class do?
 ---------------------------
 
 All of Django's fields (and when we say *fields* in this document, we always
-mean model fields and not :ref:`form fields <ref-forms-fields>`) are subclasses
+mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
 of :class:`django.db.models.Field`. Most of the information that Django records
 about a field is common to all fields -- name, help text, uniqueness and so
 forth. Storing all that information is handled by ``Field``. We'll get into the
@@ -124,7 +122,7 @@ when the model class is created (the precise details of how this is done are
 unimportant here). This is because the field classes aren't necessary when
 you're just creating and modifying attributes. Instead, they provide the
 machinery for converting between the attribute value and what is stored in the
-database or sent to the :ref:`serializer <topics-serialization>`.
+database or sent to the :doc:`serializer </topics/serialization>`.
 
 Keep this in mind when creating your own custom fields. The Django ``Field``
 subclass you write provides the machinery for converting between your Python
@@ -209,8 +207,8 @@ parameters:
     * :attr:`~django.db.models.Field.default`
     * :attr:`~django.db.models.Field.editable`
     * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
-      not be serialized when the model is passed to Django's :ref:`serializers
-      <topics-serialization>`. Defaults to ``True``.
+      not be serialized when the model is passed to Django's :doc:`serializers
+      </topics/serialization>`. Defaults to ``True``.
     * :attr:`~django.db.models.Field.unique_for_date`
     * :attr:`~django.db.models.Field.unique_for_month`
     * :attr:`~django.db.models.Field.unique_for_year`
@@ -225,8 +223,8 @@ parameters:
       inheritance. For advanced use only.
 
 All of the options without an explanation in the above list have the same
-meaning they do for normal Django fields. See the :ref:`field documentation
-<ref-models-fields>` for examples and details.
+meaning they do for normal Django fields. See the :doc:`field documentation
+</ref/models/fields>` for examples and details.
 
 The ``SubfieldBase`` metaclass
 ------------------------------
@@ -270,8 +268,8 @@ value. This means that whenever a value may be assigned to the field,
 you need to ensure that it will be of the correct datatype, or that
 you handle any exceptions.
 
-This is especially important if you use :ref:`ModelForms
-<topics-forms-modelforms>`. When saving a ModelForm, Django will use
+This is especially important if you use :doc:`ModelForms
+</topics/forms/modelforms>`. When saving a ModelForm, Django will use
 form values to instantiate model instances. However, if the cleaned
 form data can't be used as valid input to the field, the normal form
 validation process will break.
@@ -611,8 +609,8 @@ All of the ``kwargs`` dictionary is passed directly to the form field's
 :meth:`~django.forms.Field__init__` method. Normally, all you need to do is
 set up a good default for the ``form_class`` argument and then delegate further
 handling to the parent class. This might require you to write a custom form
-field (and even a form widget). See the :ref:`forms documentation
-<topics-forms-index>` for information about this, and take a look at the code in
+field (and even a form widget). See the :doc:`forms documentation
+</topics/forms/index>` for information about this, and take a look at the code in
 :mod:`django.contrib.localflavor` for some examples of custom widgets.
 
 Continuing our ongoing example, we can write the :meth:`formfield` method as::
@@ -721,7 +719,7 @@ Django provides a ``File`` class, which is used as a proxy to the file's
 contents and operations. This can be subclassed to customize how the file is
 accessed, and what methods are available. It lives at
 ``django.db.models.fields.files``, and its default behavior is explained in the
-:ref:`file documentation <ref-files-file>`.
+:doc:`file documentation </ref/files/file>`.
 
 Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
 told to use it. To do so, simply assign the new ``File`` subclass to the special

docs/howto/custom-template-tags.txt

@@ -1,5 +1,3 @@
-.. _howto-custom-template-tags:
-
 ================================
 Custom template tags and filters
 ================================
@@ -7,8 +5,8 @@ Custom template tags and filters
 Introduction
 ============
 
-Django's template system comes with a wide variety of :ref:`built-in
-tags and filters <ref-templates-builtins>` designed to address the
+Django's template system comes with a wide variety of :doc:`built-in
+tags and filters </ref/templates/builtins>` designed to address the
 presentation logic needs of your application. Nevertheless, you may
 find yourself needing functionality that is not covered by the core
 set of template primitives. You can extend the template engine by

docs/howto/deployment/fastcgi.txt

@@ -1,13 +1,11 @@
-.. _howto-deployment-fastcgi:
-
 ============================================
 How to use Django with FastCGI, SCGI, or AJP
 ============================================
 
 .. highlight:: bash
 
-Although the current preferred setup for running Django is :ref:`Apache with
-mod_wsgi <howto-deployment-modwsgi>`, many people use shared hosting, on
+Although the current preferred setup for running Django is :doc:`Apache with
+mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on
 which protocols such as FastCGI, SCGI or AJP are the only viable options. In
 some setups, these protocols may provide better performance than mod_wsgi_.
 
@@ -74,7 +72,7 @@ TCP socket. What you choose is a manner of preference; a TCP socket is usually
 easier due to permissions issues.
 
 To start your server, first change into the directory of your project (wherever
-your :ref:`manage.py <ref-django-admin>` is), and then run the
+your :doc:`manage.py </ref/django-admin>` is), and then run the
 :djadmin:`runfcgi` command::
 
     ./manage.py runfcgi [options]

docs/howto/deployment/index.txt

@@ -1,5 +1,3 @@
-.. _howto-deployment-index:
-
 Deploying Django
 ================
 
@@ -10,18 +8,18 @@ ways to easily deploy Django:
 
 .. toctree::
    :maxdepth: 1
-   
+
    modwsgi
    modpython
    fastcgi
-   
+
 If you're new to deploying Django and/or Python, we'd recommend you try
-:ref:`mod_wsgi <howto-deployment-modwsgi>` first. In most cases it'll be the easiest,
+:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
 fastest, and most stable deployment choice.
 
 .. seealso::
 
     * `Chapter 12 of The Django Book`_ discusses deployment and especially
       scaling in more detail.
-      
+
 .. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/

docs/howto/deployment/modpython.txt

@@ -1,5 +1,3 @@
-.. _howto-deployment-modpython:
-
 ============================================
 How to use Django with Apache and mod_python
 ============================================
@@ -8,7 +6,7 @@ How to use Django with Apache and mod_python
 
 The `mod_python`_ module for Apache_ can be used to deploy Django to a
 production server, although it has been mostly superseded by the simpler
-:ref:`mod_wsgi deployment option <howto-deployment-modwsgi>`.
+:doc:`mod_wsgi deployment option </howto/deployment/modwsgi>`.
 
 mod_python is similar to (and inspired by) `mod_perl`_ : It embeds Python within
 Apache and loads Python code into memory when the server starts. Code stays in
@@ -25,8 +23,8 @@ Django requires Apache 2.x and mod_python 3.x, and you should use Apache's
       Apache, there's no better source than `Apache's own official
       documentation`_
 
-    * You may also be interested in :ref:`How to use Django with FastCGI, SCGI,
-      or AJP <howto-deployment-fastcgi>`.
+    * You may also be interested in :doc:`How to use Django with FastCGI, SCGI,
+      or AJP </howto/deployment/fastcgi>`.
 
 .. _Apache: http://httpd.apache.org/
 .. _mod_python: http://www.modpython.org/
@@ -383,7 +381,7 @@ If you get a UnicodeEncodeError
 ===============================
 
 If you're taking advantage of the internationalization features of Django (see
-:ref:`topics-i18n`) and you intend to allow users to upload files, you must
+:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must
 ensure that the environment used to start Apache is configured to accept
 non-ASCII file names. If your environment is not correctly configured, you
 will trigger ``UnicodeEncodeError`` exceptions when calling functions like

docs/howto/deployment/modwsgi.txt

@@ -1,5 +1,3 @@
-.. _howto-deployment-modwsgi:
-
 ==========================================
 How to use Django with Apache and mod_wsgi
 ==========================================

docs/howto/error-reporting.txt

@@ -1,5 +1,3 @@
-.. _howto-error-reporting:
-
 Error reporting via e-mail
 ==========================
 
@@ -30,8 +28,8 @@ the HTTP request that caused the error.
    to specify :setting:`EMAIL_HOST` and possibly
    :setting:`EMAIL_HOST_USER` and :setting:`EMAIL_HOST_PASSWORD`,
    though other settings may be also required depending on your mail
-   server's configuration. Consult :ref:`the Django settings
-   documentation <ref-settings>` for a full list of email-related
+   server's configuration. Consult :doc:`the Django settings
+   documentation </ref/settings>` for a full list of email-related
    settings.
 
 By default, Django will send email from root@localhost. However, some mail

docs/howto/i18n.txt

@@ -1,5 +1,3 @@
-.. _howto-i18n:
-
 .. _using-translations-in-your-own-projects:
 
 ===============================================
@@ -46,7 +44,7 @@ To create message files, you use the :djadmin:`django-admin.py makemessages <mak
 tool. You only need to be in the same directory where the ``locale/`` directory
 is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
 to produce the binary ``.mo`` files that are used by ``gettext``. Read the
-:ref:`topics-i18n-localization` document for more details.
+:doc:`/topics/i18n/localization` document for more details.
 
 You can also run ``django-admin.py compilemessages --settings=path.to.settings``
 to make the compiler process all the directories in your :setting:`LOCALE_PATHS`

docs/howto/index.txt

@@ -1,11 +1,9 @@
-.. _howto-index:
-
 "How-to" guides
 ===============
 
 Here you'll find short answers to "How do I....?" types of questions. These
 how-to guides don't cover topics in depth -- you'll find that material in the
-:ref:`topics-index` and the :ref:`ref-index`. However, these guides will help
+:doc:`/topics/index` and the :doc:`/ref/index`. However, these guides will help
 you quickly accomplish common tasks.
 
 .. toctree::

docs/howto/initial-data.txt

@@ -1,5 +1,3 @@
-.. _howto-initial-data:
-
 =================================
 Providing initial data for models
 =================================
@@ -20,10 +18,10 @@ Providing initial data with fixtures
 
 A fixture is a collection of data that Django knows how to import into a
 database. The most straightforward way of creating a fixture if you've already
-got some data is to use the :djadmin:`manage.py dumpdata` command. Or, you can
-write fixtures by hand; fixtures can be written as XML, YAML, or JSON documents.
-The :ref:`serialization documentation <topics-serialization>` has more details
-about each of these supported :ref:`serialization formats
+got some data is to use the :djadmin:`manage.py dumpdata <dumpdata>` command.
+Or, you can write fixtures by hand; fixtures can be written as XML, YAML, or
+JSON documents. The :doc:`serialization documentation </topics/serialization>`
+has more details about each of these supported :ref:`serialization formats
 <serialization-formats>`.
 
 As an example, though, here's what a fixture for a simple ``Person`` model might
@@ -114,9 +112,9 @@ which will insert the desired data (e.g., properly-formatted
 ``INSERT`` statements separated by semicolons).
 
 The SQL files are read by the :djadmin:`sqlcustom`, :djadmin:`sqlreset`,
-:djadmin:`sqlall` and :djadmin:`reset` commands in :ref:`manage.py
-<ref-django-admin>`. Refer to the :ref:`manage.py documentation
-<ref-django-admin>` for more information.
+:djadmin:`sqlall` and :djadmin:`reset` commands in :doc:`manage.py
+</ref/django-admin>`. Refer to the :doc:`manage.py documentation
+</ref/django-admin>` for more information.
 
 Note that if you have multiple SQL data files, there's no guarantee of
 the order in which they're executed. The only thing you can assume is

docs/howto/jython.txt

@@ -1,5 +1,3 @@
-.. _howto-jython:
-
 ========================
 Running Django on Jython
 ========================

docs/howto/legacy-databases.txt

@@ -1,5 +1,3 @@
-.. _howto-legacy-databases:
-
 =========================================
 Integrating Django with a legacy database
 =========================================
@@ -9,7 +7,7 @@ possible to integrate it into legacy databases. Django includes a couple of
 utilities to automate as much of this process as possible.
 
 This document assumes you know the Django basics, as covered in the
-:ref:`tutorial <intro-tutorial01>`.
+:doc:`tutorial </intro/tutorial01>`.
 
 Once you've got Django set up, you'll follow this general process to integrate
 with an existing database.

docs/howto/outputting-csv.txt

@@ -1,5 +1,3 @@
-.. _howto-outputting-csv:
-
 ==========================
 Outputting CSV with Django
 ==========================
@@ -61,7 +59,7 @@ mention:
 Using the template system
 =========================
 
-Alternatively, you can use the :ref:`Django template system <topics-templates>`
+Alternatively, you can use the :doc:`Django template system </topics/templates>`
 to generate CSV. This is lower-level than using the convenient CSV, but the
 solution is presented here for completeness.
 
@@ -113,4 +111,4 @@ Other text-based formats
 Notice that there isn't very much specific to CSV here -- just the specific
 output format. You can use either of these techniques to output any text-based
 format you can dream of. You can also use a similar technique to generate
-arbitrary binary data; see :ref:`howto-outputting-pdf` for an example.
+arbitrary binary data; see :doc:`/howto/outputting-pdf` for an example.

docs/howto/outputting-pdf.txt

@@ -1,5 +1,3 @@
-.. _howto-outputting-pdf:
-
 ===========================
 Outputting PDFs with Django
 ===========================
@@ -154,5 +152,5 @@ Other formats
 Notice that there isn't a lot in these examples that's PDF-specific -- just the
 bits using ``reportlab``. You can use a similar technique to generate any
 arbitrary format that you can find a Python library for. Also see
-:ref:`howto-outputting-csv` for another example and some techniques you can use
+:doc:`/howto/outputting-csv` for another example and some techniques you can use
 when generated text-based formats.

docs/howto/static-files.txt

@@ -1,5 +1,3 @@
-.. _howto-static-files:
-
 =========================
 How to serve static files
 =========================
@@ -42,7 +40,7 @@ Here's the formal definition of the :func:`~django.views.static.serve` view:
 
 .. function:: def serve(request, path, document_root, show_indexes=False)
 
-To use it, just put this in your :ref:`URLconf <topics-http-urls>`::
+To use it, just put this in your :doc:`URLconf </topics/http/urls>`::
 
     (r'^site_media/(?P<path>.*)$', 'django.views.static.serve',
             {'document_root': '/path/to/media'}),
@@ -71,7 +69,7 @@ required. For example, if we have a line in ``settings.py`` that says::
 
     STATIC_DOC_ROOT = '/path/to/media'
 
-...we could write the above :ref:`URLconf <topics-http-urls>` entry as::
+...we could write the above :doc:`URLconf </topics/http/urls>` entry as::
 
     from django.conf import settings
     ...

docs/index.txt

@@ -12,10 +12,10 @@ Getting help
 
 Having trouble? We'd like to help!
 
-* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common questions.
+* Try the :doc:`FAQ <faq/index>` -- it's got answers to many common questions.
 
 * Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or
-  the :ref:`detailed table of contents <contents>`.
+  the :doc:`detailed table of contents <contents>`.
 
 * Search for information in the `archives of the django-users mailing list`_, or
   `post a question`_.
@@ -35,179 +35,179 @@ First steps
 ===========
 
     * **From scratch:**
-      :ref:`Overview <intro-overview>` |
-      :ref:`Installation <intro-install>`
+      :doc:`Overview <intro/overview>` |
+      :doc:`Installation <intro/install>`
 
     * **Tutorial:**
-      :ref:`Part 1 <intro-tutorial01>` |
-      :ref:`Part 2 <intro-tutorial02>` |
-      :ref:`Part 3 <intro-tutorial03>` |
-      :ref:`Part 4 <intro-tutorial04>`
+      :doc:`Part 1 <intro/tutorial01>` |
+      :doc:`Part 2 <intro/tutorial02>` |
+      :doc:`Part 3 <intro/tutorial03>` |
+      :doc:`Part 4 <intro/tutorial04>`
 
 The model layer
 ===============
 
     * **Models:**
-      :ref:`Model syntax <topics-db-models>` |
-      :ref:`Field types <ref-models-fields>` |
-      :ref:`Meta options <ref-models-options>`
+      :doc:`Model syntax <topics/db/models>` |
+      :doc:`Field types <ref/models/fields>` |
+      :doc:`Meta options <ref/models/options>`
 
     * **QuerySets:**
-      :ref:`Executing queries <topics-db-queries>` |
-      :ref:`QuerySet method reference <ref-models-querysets>`
+      :doc:`Executing queries <topics/db/queries>` |
+      :doc:`QuerySet method reference <ref/models/querysets>`
 
     * **Model instances:**
-      :ref:`Instance methods <ref-models-instances>` |
-      :ref:`Accessing related objects <ref-models-relations>`
+      :doc:`Instance methods <ref/models/instances>` |
+      :doc:`Accessing related objects <ref/models/relations>`
 
     * **Advanced:**
-      :ref:`Managers <topics-db-managers>` |
-      :ref:`Raw SQL <topics-db-sql>` |
-      :ref:`Transactions <topics-db-transactions>` |
-      :ref:`Aggregation <topics-db-aggregation>` |
-      :ref:`Custom fields <howto-custom-model-fields>` |
-      :ref:`Multiple databases <topics-db-multi-db>`
+      :doc:`Managers <topics/db/managers>` |
+      :doc:`Raw SQL <topics/db/sql>` |
+      :doc:`Transactions <topics/db/transactions>` |
+      :doc:`Aggregation <topics/db/aggregation>` |
+      :doc:`Custom fields <howto/custom-model-fields>` |
+      :doc:`Multiple databases <topics/db/multi-db>`
 
     * **Other:**
-      :ref:`Supported databases <ref-databases>` |
-      :ref:`Legacy databases <howto-legacy-databases>` |
-      :ref:`Providing initial data <howto-initial-data>` |
-      :ref:`Optimize database access <topics-db-optimization>`
+      :doc:`Supported databases <ref/databases>` |
+      :doc:`Legacy databases <howto/legacy-databases>` |
+      :doc:`Providing initial data <howto/initial-data>` |
+      :doc:`Optimize database access <topics/db/optimization>`
 
 The template layer
 ==================
 
     * **For designers:**
-      :ref:`Syntax overview <topics-templates>` |
-      :ref:`Built-in tags and filters <ref-templates-builtins>`
+      :doc:`Syntax overview <topics/templates>` |
+      :doc:`Built-in tags and filters <ref/templates/builtins>`
 
     * **For programmers:**
-      :ref:`Template API <ref-templates-api>` |
-      :ref:`Custom tags and filters <howto-custom-template-tags>`
+      :doc:`Template API <ref/templates/api>` |
+      :doc:`Custom tags and filters <howto/custom-template-tags>`
 
 The view layer
 ==============
 
     * **The basics:**
-      :ref:`URLconfs <topics-http-urls>` |
-      :ref:`View functions <topics-http-views>` |
-      :ref:`Shortcuts <topics-http-shortcuts>`
+      :doc:`URLconfs <topics/http/urls>` |
+      :doc:`View functions <topics/http/views>` |
+      :doc:`Shortcuts <topics/http/shortcuts>`
 
-    * **Reference:**  :ref:`Request/response objects <ref-request-response>`
+    * **Reference:**  :doc:`Request/response objects <ref/request-response>`
 
     * **File uploads:**
-      :ref:`Overview <topics-http-file-uploads>` |
-      :ref:`File objects <ref-files-file>` |
-      :ref:`Storage API <ref-files-storage>` |
-      :ref:`Managing files <topics-files>` |
-      :ref:`Custom storage <howto-custom-file-storage>`
+      :doc:`Overview <topics/http/file-uploads>` |
+      :doc:`File objects <ref/files/file>` |
+      :doc:`Storage API <ref/files/storage>` |
+      :doc:`Managing files <topics/files>` |
+      :doc:`Custom storage <howto/custom-file-storage>`
 
     * **Generic views:**
-      :ref:`Overview<topics-generic-views>` |
-      :ref:`Built-in generic views<ref-generic-views>`
+      :doc:`Overview<topics/generic-views>` |
+      :doc:`Built-in generic views<ref/generic-views>`
 
     * **Advanced:**
-      :ref:`Generating CSV <howto-outputting-csv>` |
-      :ref:`Generating PDF <howto-outputting-pdf>`
+      :doc:`Generating CSV <howto/outputting-csv>` |
+      :doc:`Generating PDF <howto/outputting-pdf>`
 
     * **Middleware:**
-      :ref:`Overview <topics-http-middleware>` |
-      :ref:`Built-in middleware classes <ref-middleware>`
+      :doc:`Overview <topics/http/middleware>` |
+      :doc:`Built-in middleware classes <ref/middleware>`
 
 Forms
 =====
 
     * **The basics:**
-      :ref:`Overview <topics-forms-index>` |
-      :ref:`Form API <ref-forms-api>` |
-      :ref:`Built-in fields <ref-forms-fields>` |
-      :ref:`Built-in widgets <ref-forms-widgets>`
+      :doc:`Overview <topics/forms/index>` |
+      :doc:`Form API <ref/forms/api>` |
+      :doc:`Built-in fields <ref/forms/fields>` |
+      :doc:`Built-in widgets <ref/forms/widgets>`
 
     * **Advanced:**
-      :ref:`Forms for models <topics-forms-modelforms>` |
-      :ref:`Integrating media <topics-forms-media>` |
-      :ref:`Formsets <topics-forms-formsets>` |
-      :ref:`Customizing validation <ref-forms-validation>`
+      :doc:`Forms for models <topics/forms/modelforms>` |
+      :doc:`Integrating media <topics/forms/media>` |
+      :doc:`Formsets <topics/forms/formsets>` |
+      :doc:`Customizing validation <ref/forms/validation>`
 
     * **Extras:**
-      :ref:`Form preview <ref-contrib-formtools-form-preview>` |
-      :ref:`Form wizard <ref-contrib-formtools-form-wizard>`
+      :doc:`Form preview <ref/contrib/formtools/form-preview>` |
+      :doc:`Form wizard <ref/contrib/formtools/form-wizard>`
 
 The development process
 =======================
 
     * **Settings:**
-      :ref:`Overview <topics-settings>` |
-      :ref:`Full list of settings <ref-settings>`
+      :doc:`Overview <topics/settings>` |
+      :doc:`Full list of settings <ref/settings>`
 
     * **Exceptions:**
-      :ref:`Overview <ref-exceptions>`
+      :doc:`Overview <ref/exceptions>`
 
     * **django-admin.py and manage.py:**
-      :ref:`Overview <ref-django-admin>` |
-      :ref:`Adding custom commands <howto-custom-management-commands>`
+      :doc:`Overview <ref/django-admin>` |
+      :doc:`Adding custom commands <howto/custom-management-commands>`
 
-    * **Testing:**  :ref:`Overview <topics-testing>`
+    * **Testing:**  :doc:`Overview <topics/testing>`
 
     * **Deployment:**
-      :ref:`Overview <howto-deployment-index>` |
-      :ref:`Apache/mod_wsgi <howto-deployment-modwsgi>` |
-      :ref:`Apache/mod_python <howto-deployment-modpython>` |
-      :ref:`FastCGI/SCGI/AJP <howto-deployment-fastcgi>` |
-      :ref:`Apache authentication <howto-apache-auth>` |
-      :ref:`Serving static files <howto-static-files>` |
-      :ref:`Tracking code errors by e-mail <howto-error-reporting>`
+      :doc:`Overview <howto/deployment/index>` |
+      :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
+      :doc:`Apache/mod_python <howto/deployment/modpython>` |
+      :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
+      :doc:`Apache authentication <howto/apache-auth>` |
+      :doc:`Serving static files <howto/static-files>` |
+      :doc:`Tracking code errors by e-mail <howto/error-reporting>`
 
 Other batteries included
 ========================
 
-    * :ref:`Admin site <ref-contrib-admin>` | :ref:`Admin actions <ref-contrib-admin-actions>`
-    * :ref:`Authentication <topics-auth>`
-    * :ref:`Cache system <topics-cache>`
-    * :ref:`Conditional content processing <topics-conditional-processing>`
-    * :ref:`Comments <ref-contrib-comments-index>` | :ref:`Moderation <ref-contrib-comments-moderation>` | :ref:`Custom comments <ref-contrib-comments-custom>`
-    * :ref:`Content types <ref-contrib-contenttypes>`
-    * :ref:`Cross Site Request Forgery protection <ref-contrib-csrf>`
-    * :ref:`Databrowse <ref-contrib-databrowse>`
-    * :ref:`E-mail (sending) <topics-email>`
-    * :ref:`Flatpages <ref-contrib-flatpages>`
-    * :ref:`GeoDjango <ref-contrib-gis>`
-    * :ref:`Humanize <ref-contrib-humanize>`
-    * :ref:`Internationalization <topics-i18n>`
-    * :ref:`Jython support <howto-jython>`
-    * :ref:`"Local flavor" <ref-contrib-localflavor>`
-    * :ref:`Messages <ref-contrib-messages>`
-    * :ref:`Pagination <topics-pagination>`
-    * :ref:`Redirects <ref-contrib-redirects>`
-    * :ref:`Serialization <topics-serialization>`
-    * :ref:`Sessions <topics-http-sessions>`
-    * :ref:`Signals <topics-signals>`
-    * :ref:`Sitemaps <ref-contrib-sitemaps>`
-    * :ref:`Sites <ref-contrib-sites>`
-    * :ref:`Syndication feeds (RSS/Atom) <ref-contrib-syndication>`
-    * :ref:`Unicode in Django <ref-unicode>`
-    * :ref:`Web design helpers <ref-contrib-webdesign>`
-    * :ref:`Validators <ref-validators>`
+    * :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>`
+    * :doc:`Authentication <topics/auth>`
+    * :doc:`Cache system <topics/cache>`
+    * :doc:`Conditional content processing <topics/conditional-view-processing>`
+    * :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
+    * :doc:`Content types <ref/contrib/contenttypes>`
+    * :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
+    * :doc:`Databrowse <ref/contrib/databrowse>`
+    * :doc:`E-mail (sending) <topics/email>`
+    * :doc:`Flatpages <ref/contrib/flatpages>`
+    * :doc:`GeoDjango <ref/contrib/gis/index>`
+    * :doc:`Humanize <ref/contrib/humanize>`
+    * :doc:`Internationalization <topics/i18n/index>`
+    * :doc:`Jython support <howto/jython>`
+    * :doc:`"Local flavor" <ref/contrib/localflavor>`
+    * :doc:`Messages <ref/contrib/messages>`
+    * :doc:`Pagination <topics/pagination>`
+    * :doc:`Redirects <ref/contrib/redirects>`
+    * :doc:`Serialization <topics/serialization>`
+    * :doc:`Sessions <topics/http/sessions>`
+    * :doc:`Signals <topics/signals>`
+    * :doc:`Sitemaps <ref/contrib/sitemaps>`
+    * :doc:`Sites <ref/contrib/sites>`
+    * :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
+    * :doc:`Unicode in Django <ref/unicode>`
+    * :doc:`Web design helpers <ref/contrib/webdesign>`
+    * :doc:`Validators <ref/validators>`
 
 The Django open-source project
 ==============================
 
     * **Community:**
-      :ref:`How to get involved <internals-contributing>` |
-      :ref:`The release process <internals-release-process>` |
-      :ref:`Team of committers <internals-committers>` |
-      :ref:`The Django source code repository <internals-svn>`
+      :doc:`How to get involved <internals/contributing>` |
+      :doc:`The release process <internals/release-process>` |
+      :doc:`Team of committers <internals/committers>` |
+      :doc:`The Django source code repository <internals/svn>`
 
     * **Design philosophies:**
-      :ref:`Overview <misc-design-philosophies>`
+      :doc:`Overview <misc/design-philosophies>`
 
     * **Documentation:**
-      :ref:`About this documentation <internals-documentation>`
+      :doc:`About this documentation <internals/documentation>`
 
     * **Third-party distributions:**
-      :ref:`Overview <misc-distributions>`
+      :doc:`Overview <misc/distributions>`
 
     * **Django over time:**
-      :ref:`API stability <misc-api-stability>` |
-      :ref:`Release notes and upgrading instructions <releases-index>` |
-      :ref:`Deprecation Timeline <internals-deprecation>`
+      :doc:`API stability <misc/api-stability>` |
+      :doc:`Release notes and upgrading instructions <releases/index>` |
+      :doc:`Deprecation Timeline <internals/deprecation>`

docs/internals/committers.txt

@@ -1,5 +1,3 @@
-.. _internals-committers:
-
 =================
 Django committers
 =================

docs/internals/contributing.txt

@@ -1,5 +1,3 @@
-.. _internals-contributing:
-
 ======================
 Contributing to Django
 ======================
@@ -42,7 +40,7 @@ amount of overhead involved in working with any bug tracking system, so your
 help in keeping our ticket tracker as useful as possible is appreciated.  In
 particular:
 
-    * **Do** read the :ref:`FAQ <faq-index>` to see if your issue might be a well-known question.
+    * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question.
 
     * **Do** `search the tracker`_ to see if your issue has already been filed.
 
@@ -398,7 +396,7 @@ Various parts of Django, such as the admin site and validation error messages,
 are internationalized. This means they display different text depending on a
 user's language setting. For this, Django uses the same internationalization
 infrastructure available to Django applications described in the
-:ref:`i18n documentation<topics-i18n>`.
+:doc:`i18n documentation</topics/i18n/index>`.
 
 These translations are contributed by Django users worldwide. If you find an
 incorrect translation, or if you'd like to add a language that isn't yet
@@ -409,7 +407,7 @@ translated, here's what to do:
     * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
 
     * Create translations using the methods described in the
-      :ref:`localization documentation <topics-i18n-localization>`. For this
+      :doc:`localization documentation </topics/i18n/localization>`. For this
       you will use the ``django-admin.py makemessages`` tool. In this
       particular case it should be run from the top-level ``django`` directory
       of the Django source tree.
@@ -535,8 +533,8 @@ Please follow these coding standards when writing code for inclusion in Django:
     * Use ``InitialCaps`` for class names (or for factory functions that
       return classes).
 
-    * Mark all strings for internationalization; see the :ref:`i18n
-      documentation <topics-i18n>` for details.
+    * Mark all strings for internationalization; see the :doc:`i18n
+      documentation </topics/i18n/index>` for details.
 
     * In docstrings, use "action words" such as::
 
@@ -698,8 +696,8 @@ General improvements, or other changes to the APIs that should be emphasized
 should use the ".. versionchanged:: X.Y" directive (with the same format as the
 ``versionadded`` mentioned above.
 
-There's a full page of information about the :ref:`Django documentation
-system <internals-documentation>` that you should read prior to working on the
+There's a full page of information about the :doc:`Django documentation
+system </internals/documentation>` that you should read prior to working on the
 documentation.
 
 Guidelines for ReST files
@@ -829,7 +827,7 @@ The tests cover:
 We appreciate any and all contributions to the test suite!
 
 The Django tests all use the testing infrastructure that ships with Django for
-testing applications. See :ref:`Testing Django applications <topics-testing>`
+testing applications. See :doc:`Testing Django applications </topics/testing>`
 for an explanation of how to write new tests.
 
 Running the unit tests
@@ -1017,8 +1015,8 @@ for feature branches:
        public, please add the branch to the `Django branches`_ wiki page.
 
     2. Feature branches using SVN have a higher bar. If you want a branch in SVN
-       itself, you'll need a "mentor" among the :ref:`core committers
-       <internals-committers>`. This person is responsible for actually creating
+       itself, you'll need a "mentor" among the :doc:`core committers
+       </internals/committers>`. This person is responsible for actually creating
        the branch, monitoring your process (see below), and ultimately merging
        the branch into trunk.
 

docs/internals/deprecation.txt

@@ -1,5 +1,3 @@
-.. _internals-deprecation:
-
 ===========================
 Django Deprecation Timeline
 ===========================
@@ -52,7 +50,7 @@ their deprecation, as per the :ref:`Django deprecation policy
           associated methods (``user.message_set.create()`` and
           ``user.get_and_delete_messages()``), which have
           been deprecated since the 1.2 release, will be removed.  The
-          :ref:`messages framework <ref-contrib-messages>` should be used
+          :doc:`messages framework </ref/contrib/messages>` should be used
           instead.
 
         * Authentication backends need to support the ``obj`` parameter for

docs/internals/documentation.txt

@@ -1,5 +1,3 @@
-.. _internals-documentation:
-
 How the Django documentation works
 ==================================
 
@@ -88,27 +86,55 @@ __ http://sphinx.pocoo.org/markup/desc.html
 An example
 ----------
 
-For a quick example of how it all fits together, check this out:
+For a quick example of how it all fits together, consider this hypothetical
+example:
 
-    * First, the ``ref/settings.txt`` document starts out like this::
+    * First, the ``ref/settings.txt`` document could have an overall layout
+      like this:
 
-        .. _ref-settings:
+      .. code-block:: rst
 
-        Available settings
-        ==================
+        ========
+        Settings
+        ========
 
         ...
 
-    * Next, if you look at the ``topics/settings.txt`` document, you can see how
-      a link to ``ref/settings`` works::
+        .. _available-settings:
 
         Available settings
         ==================
 
-        For a full list of available settings, see the :ref:`settings reference
-        <ref-settings>`.
+        ...
+
+        .. _deprecated-settings:
+
+        Deprecated settings
+        ===================
+
+        ...
+
+    * Next, the ``topics/settings.txt`` document could contain something like
+      this:
+
+      .. code-block:: rst
+
+        You can access a :ref:`listing of all available settings
+        <available-settings>`. For a list of deprecated settings see
+        :ref:`deprecated-settings`.
+
+        You can find both in the :doc:`settings reference document </ref/settings>`.
+
+      We use the Sphinx doc_ cross reference element when we want to link to
+      another document as a whole and the ref_ element when we want to link to
+      an arbitrary location in a document.
+
+.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
+.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
+
+    * Next, notice how the settings are annotated:
 
-    * Next, notice how the settings (right now just the top few) are annotated::
+      .. code-block:: rst
 
         .. setting:: ADMIN_FOR
 

docs/internals/index.txt

@@ -1,5 +1,3 @@
-.. _internals-index:
-
 Django internals
 ================
 

docs/internals/release-process.txt

@@ -1,5 +1,3 @@
-.. _internals-release-process:
-
 ========================
 Django's release process
 ========================

docs/internals/svn.txt

@@ -1,5 +1,3 @@
-.. _internals-svn:
-
 =================================
 The Django source code repository
 =================================
@@ -87,8 +85,8 @@ the ``django`` module within your checkout.
 
 If you're going to be working on Django's code (say, to fix a bug or
 develop a new feature), you can probably stop reading here and move
-over to :ref:`the documentation for contributing to Django
-<internals-contributing>`, which covers things like the preferred
+over to :doc:`the documentation for contributing to Django
+</internals/contributing>`, which covers things like the preferred
 coding style and how to generate and submit a patch.
 
 
@@ -129,20 +127,20 @@ part of Django itself, and so are no longer separately maintained:
   object-relational mapper. This has been part of Django since the 1.0
   release, as the bundled application ``django.contrib.gis``.
 
-* ``i18n``: Added :ref:`internationalization support <topics-i18n>` to
+* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
   Django. This has been part of Django since the 0.90 release.
 
 * ``magic-removal``: A major refactoring of both the internals and
   public APIs of Django's object-relational mapper. This has been part
   of Django since the 0.95 release.
 
-* ``multi-auth``: A refactoring of :ref:`Django's bundled
-  authentication framework <topics-auth>` which added support for
+* ``multi-auth``: A refactoring of :doc:`Django's bundled
+  authentication framework </topics/auth>` which added support for
   :ref:`authentication backends <authentication-backends>`. This has
   been part of Django since the 0.95 release.
 
-* ``new-admin``: A refactoring of :ref:`Django's bundled
-  administrative application <ref-contrib-admin>`. This became part of
+* ``new-admin``: A refactoring of :doc:`Django's bundled
+  administrative application </ref/contrib/admin/index>`. This became part of
   Django as of the 0.91 release, but was superseded by another
   refactoring (see next listing) prior to the Django 1.0 release.
 

docs/intro/index.txt

@@ -1,5 +1,3 @@
-.. _intro-index:
-
 Getting started
 ===============
 

docs/intro/install.txt

@@ -1,10 +1,8 @@
-.. _intro-install:
-
 Quick install guide
 ===================
 
 Before you can use Django, you'll need to get it installed. We have a
-:ref:`complete installation guide <topics-install>` that covers all the
+:doc:`complete installation guide </topics/install>` that covers all the
 possibilities; this guide will guide you to a simple, minimal installation
 that'll work while you walk through the introduction.
 
@@ -14,7 +12,7 @@ Install Python
 Being a Python Web framework, Django requires Python. It works with any Python
 version from 2.4 to 2.7 (due to backwards
 incompatibilities in Python 3.0, Django does not currently work with
-Python 3.0; see :ref:`the Django FAQ <faq-install>` for more
+Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
 information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_.
 
 .. _sqlite: http://sqlite.org/
@@ -25,17 +23,17 @@ probably already have it installed.
 .. admonition:: Django on Jython
 
     If you use Jython_ (a Python implementation for the Java platform), you'll
-    need to follow a few additional steps. See :ref:`howto-jython` for details.
+    need to follow a few additional steps. See :doc:`/howto/jython` for details.
 
 .. _jython: http://www.jython.org/
 
 You can verify that Python's installed by typing ``python`` from your shell; you should see something like::
 
-    Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17) 
+    Python 2.5.1 (r251:54863, Jan 17 2008, 19:35:17)
     [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
     Type "help", "copyright", "credits" or "license" for more information.
     >>>
-    
+
 Set up a database
 -----------------
 
@@ -57,18 +55,18 @@ Install Django
 
 You've got three easy options to install Django:
 
-    * Install a version of Django :ref:`provided by your operating system
-      distribution <misc-distributions>`. This is the quickest option for those
+    * Install a version of Django :doc:`provided by your operating system
+      distribution </misc/distributions>`. This is the quickest option for those
       who have operating systems that distribute Django.
 
     * :ref:`Install an official release <installing-official-release>`. This
       is the best approach for users who want a stable version number and aren't
       concerned about running a slightly older version of Django.
-      
+
     * :ref:`Install the latest development version
       <installing-development-version>`. This is best for users who want the
       latest-and-greatest features and aren't afraid of running brand-new code.
-      
+
 .. warning::
 
     If you do either of the first two steps, keep an eye out for parts of the
@@ -79,7 +77,7 @@ You've got three easy options to install Django:
 That's it!
 ----------
 
-That's it -- you can now :ref:`move onto the tutorial <intro-tutorial01>`.
+That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`.
 
 
 

docs/intro/overview.txt

@@ -1,5 +1,3 @@
-.. _intro-overview:
-
 ==================
 Django at a glance
 ==================
@@ -11,8 +9,8 @@ overview of how to write a database-driven Web app with Django.
 The goal of this document is to give you enough technical specifics to
 understand how Django works, but this isn't intended to be a tutorial or
 reference -- but we've got both! When you're ready to start a project, you can
-:ref:`start with the tutorial <intro-tutorial01>` or :ref:`dive right into more
-detailed documentation <topics-index>`.
+:doc:`start with the tutorial </intro/tutorial01>` or :doc:`dive right into more
+detailed documentation </topics/index>`.
 
 Design your model
 =================
@@ -21,7 +19,7 @@ Although you can use Django without a database, it comes with an
 object-relational mapper in which you describe your database layout in Python
 code.
 
-The :ref:`data-model syntax <topics-db-models>` offers many rich ways of
+The :doc:`data-model syntax </topics/db/models>` offers many rich ways of
 representing your models -- so far, it's been solving two years' worth of
 database-schema problems. Here's a quick example::
 
@@ -56,7 +54,7 @@ tables in your database for whichever tables don't already exist.
 Enjoy the free API
 ==================
 
-With that, you've got a free, and rich, :ref:`Python API <topics-db-queries>` to
+With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>` to
 access your data. The API is created on the fly, no code generation necessary::
 
     >>> from mysite.models import Reporter, Article
@@ -131,7 +129,7 @@ A dynamic admin interface: it's not just scaffolding -- it's the whole house
 ============================================================================
 
 Once your models are defined, Django can automatically create a professional,
-production ready :ref:`administrative interface <ref-contrib-admin>` -- a Web
+production ready :doc:`administrative interface </ref/contrib/admin/index>` -- a Web
 site that lets authenticated users add, change and delete objects. It's as easy
 as registering your model in the admin site::
 
@@ -168,8 +166,8 @@ A clean, elegant URL scheme is an important detail in a high-quality Web
 application. Django encourages beautiful URL design and doesn't put any cruft
 in URLs, like ``.php`` or ``.asp``.
 
-To design URLs for an app, you create a Python module called a :ref:`URLconf
-<topics-http-urls>`. A table of contents for your app, it contains a simple mapping
+To design URLs for an app, you create a Python module called a :doc:`URLconf
+</topics/http/urls>`. A table of contents for your app, it contains a simple mapping
 between URL patterns and Python callback functions. URLconfs also serve to
 decouple URLs from Python code.
 
@@ -216,7 +214,7 @@ and renders the template with the retrieved data. Here's an example view for
         a_list = Article.objects.filter(pub_date__year=year)
         return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})
 
-This example uses Django's :ref:`template system <topics-templates>`, which has
+This example uses Django's :doc:`template system </topics/templates>`, which has
 several powerful features but strives to stay simple enough for non-programmers
 to use.
 
@@ -307,17 +305,17 @@ This is just the surface
 This has been only a quick overview of Django's functionality. Some more useful
 features:
 
-    * A :ref:`caching framework <topics-cache>` that integrates with memcached
+    * A :doc:`caching framework </topics/cache>` that integrates with memcached
       or other backends.
 
-    * A :ref:`syndication framework <ref-contrib-syndication>` that makes
+    * A :doc:`syndication framework </ref/contrib/syndication>` that makes
       creating RSS and Atom feeds as easy as writing a small Python class.
 
     * More sexy automatically-generated admin features -- this overview barely
       scratched the surface.
 
-The next obvious steps are for you to `download Django`_, read :ref:`the
-tutorial <intro-tutorial01>` and join `the community`_. Thanks for your
+The next obvious steps are for you to `download Django`_, read :doc:`the
+tutorial </intro/tutorial01>` and join `the community`_. Thanks for your
 interest!
 
 .. _download Django: http://www.djangoproject.com/download/

docs/intro/tutorial01.txt

@@ -1,5 +1,3 @@
-.. _intro-tutorial01:
-
 =====================================
 Writing your first Django app, part 1
 =====================================
@@ -14,7 +12,7 @@ It'll consist of two parts:
     * A public site that lets people view polls and vote in them.
     * An admin site that lets you add, change and delete polls.
 
-We'll assume you have :ref:`Django installed <intro-install>` already. You can
+We'll assume you have :doc:`Django installed </intro/install>` already. You can
 tell Django is installed by running the Python interactive interpreter and
 typing ``import django``. If that command runs successfully, with no errors,
 Django is installed.
@@ -47,8 +45,8 @@ create a ``mysite`` directory in your current directory.
    you try to run ``django-admin.py startproject``. This is because, on
    Unix-based systems like OS X, a file must be marked as "executable" before it
    can be run as a program. To do this, open Terminal.app and navigate (using
-   the ``cd`` command) to the directory where :ref:`django-admin.py
-   <ref-django-admin>` is installed, then run the command
+   the ``cd`` command) to the directory where :doc:`django-admin.py
+   </ref/django-admin>` is installed, then run the command
    ``chmod +x django-admin.py``.
 
 .. note::
@@ -58,11 +56,11 @@ create a ``mysite`` directory in your current directory.
     ``django`` (which will conflict with Django itself) or ``test`` (which
     conflicts with a built-in Python package).
 
-:ref:`django-admin.py <ref-django-admin>` should be on your system path if you
+:doc:`django-admin.py </ref/django-admin>` should be on your system path if you
 installed Django via ``python setup.py``. If it's not on your path, you can find
 it in ``site-packages/django/bin``, where ```site-packages``` is a directory
-within your Python installation. Consider symlinking to :ref:`django-admin.py
-<ref-django-admin>` from some place on your path, such as
+within your Python installation. Consider symlinking to :doc:`django-admin.py
+</ref/django-admin>` from some place on your path, such as
 :file:`/usr/local/bin`.
 
 .. admonition:: Where should this code live?
@@ -93,14 +91,14 @@ These files are:
 
     * :file:`manage.py`: A command-line utility that lets you interact with this
       Django project in various ways. You can read all the details about
-      :file:`manage.py` in :ref:`ref-django-admin`.
+      :file:`manage.py` in :doc:`/ref/django-admin`.
 
     * :file:`settings.py`: Settings/configuration for this Django project.
-      :ref:`topics-settings` will tell you all about how settings work.
+      :doc:`/topics/settings` will tell you all about how settings work.
 
     * :file:`urls.py`: The URL declarations for this Django project; a "table of
       contents" of your Django-powered site. You can read more about URLs in
-      :ref:`topics-http-urls`.
+      :doc:`/topics/http/urls`.
 
 .. _more about packages: http://docs.python.org/tutorial/modules.html#packages
 
@@ -473,7 +471,7 @@ added to your project since the last time you ran syncdb. :djadmin:`syncdb` can
 be called as often as you like, and it will only ever create the tables that
 don't exist.
 
-Read the :ref:`django-admin.py documentation <ref-django-admin>` for full
+Read the :doc:`django-admin.py documentation </ref/django-admin>` for full
 information on what the ``manage.py`` utility can do.
 
 Playing with the API
@@ -508,10 +506,10 @@ things:
     set the ``DJANGO_SETTINGS_MODULE`` environment variable to
     ``mysite.settings``.
 
-    For more information on all of this, see the :ref:`django-admin.py
-    documentation <ref-django-admin>`.
+    For more information on all of this, see the :doc:`django-admin.py
+    documentation </ref/django-admin>`.
 
-Once you're in the shell, explore the :ref:`database API <topics-db-queries>`::
+Once you're in the shell, explore the :doc:`database API </topics/db/queries>`::
 
     >>> from mysite.polls.models import Poll, Choice # Import the model classes we just wrote.
 
@@ -570,8 +568,8 @@ of this object. Let's fix that by editing the polls model (in the
    models and don't see any change in how they're represented, you're most
    likely using an old version of Django. (This version of the tutorial is
    written for the latest development version of Django.) If you're using a
-   Subversion checkout of Django's development version (see :ref:`the
-   installation docs <topics-install>` for more information), you shouldn't have
+   Subversion checkout of Django's development version (see :doc:`the
+   installation docs </topics/install>` for more information), you shouldn't have
    any problems.
 
    If you want to stick with an older version of Django, you'll want to switch
@@ -693,9 +691,9 @@ Save these changes and start a new Python interactive shell by running
     >>> c = p.choice_set.filter(choice__startswith='Just hacking')
     >>> c.delete()
 
-For more information on model relations, see :ref:`Accessing related objects
-<ref-models-relations>`. For full details on the database API, see our
-:ref:`Database API reference <topics-db-queries>`.
+For more information on model relations, see :doc:`Accessing related objects
+</ref/models/relations>`. For full details on the database API, see our
+:doc:`Database API reference </topics/db/queries>`.
 
-When you're comfortable with the API, read :ref:`part 2 of this tutorial
-<intro-tutorial02>` to get Django's automatic admin working.
+When you're comfortable with the API, read :doc:`part 2 of this tutorial
+</intro/tutorial02>` to get Django's automatic admin working.

docs/intro/tutorial02.txt

@@ -1,10 +1,8 @@
-.. _intro-tutorial02:
-
 =====================================
 Writing your first Django app, part 2
 =====================================
 
-This tutorial begins where :ref:`Tutorial 1 <intro-tutorial01>` left off. We're
+This tutorial begins where :doc:`Tutorial 1 </intro/tutorial01>` left off. We're
 continuing the Web-poll application and will focus on Django's
 automatically-generated admin site.
 
@@ -463,5 +461,5 @@ object-specific admin pages in whatever way you think is best. Again,
 don't worry if you can't understand the template language -- we'll cover that
 in more detail in Tutorial 3.
 
-When you're comfortable with the admin site, read :ref:`part 3 of this tutorial
-<intro-tutorial03>` to start working on public poll views.
+When you're comfortable with the admin site, read :doc:`part 3 of this tutorial
+</intro/tutorial03>` to start working on public poll views.

docs/intro/tutorial03.txt

@@ -1,10 +1,8 @@
-.. _intro-tutorial03:
-
 =====================================
 Writing your first Django app, part 3
 =====================================
 
-This tutorial begins where :ref:`Tutorial 2 <intro-tutorial02>` left off. We're
+This tutorial begins where :doc:`Tutorial 2 </intro/tutorial02>` left off. We're
 continuing the Web-poll application and will focus on creating the public
 interface -- "views."
 
@@ -68,8 +66,8 @@ arbitrary keyword arguments from the dictionary (an optional third item in the
 tuple).
 
 For more on :class:`~django.http.HttpRequest` objects, see the
-:ref:`ref-request-response`. For more details on URLconfs, see the
-:ref:`topics-http-urls`.
+:doc:`/ref/request-response`. For more details on URLconfs, see the
+:doc:`/topics/http/urls`.
 
 When you ran ``django-admin.py startproject mysite`` at the beginning of
 Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also
@@ -205,7 +203,7 @@ you want, using whatever Python libraries you want.
 All Django wants is that :class:`~django.http.HttpResponse`. Or an exception.
 
 Because it's convenient, let's use Django's own database API, which we covered
-in :ref:`Tutorial 1 <intro-tutorial01>`. Here's one stab at the ``index()``
+in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at the ``index()``
 view, which displays the latest 5 poll questions in the system, separated by
 commas, according to publication date::
 
@@ -425,7 +423,7 @@ Method-calling happens in the ``{% for %}`` loop: ``poll.choice_set.all`` is
 interpreted as the Python code ``poll.choice_set.all()``, which returns an
 iterable of Choice objects and is suitable for use in the ``{% for %}`` tag.
 
-See the :ref:`template guide <topics-templates>` for more about templates.
+See the :doc:`template guide </topics/templates>` for more about templates.
 
 Simplifying the URLconfs
 ========================
@@ -514,5 +512,5 @@ under "/content/polls/", or any other URL root, and the app will still work.
 
 All the poll app cares about is its relative URLs, not its absolute URLs.
 
-When you're comfortable with writing views, read :ref:`part 4 of this tutorial
-<intro-tutorial04>` to learn about simple form processing and generic views.
+When you're comfortable with writing views, read :doc:`part 4 of this tutorial
+</intro/tutorial04>` to learn about simple form processing and generic views.

docs/intro/tutorial04.txt

@@ -1,10 +1,8 @@
-.. _intro-tutorial04:
-
 =====================================
 Writing your first Django app, part 4
 =====================================
 
-This tutorial begins where :ref:`Tutorial 3 <intro-tutorial03>` left off. We're
+This tutorial begins where :doc:`Tutorial 3 </intro/tutorial03>` left off. We're
 continuing the Web-poll application and will focus on simple form processing and
 cutting down our code.
 
@@ -70,7 +68,7 @@ The details of how this works are explained in the documentation for
 :ref:`RequestContext <subclassing-context-requestcontext>`.
 
 Now, let's create a Django view that handles the submitted data and does
-something with it. Remember, in :ref:`Tutorial 3 <intro-tutorial03>`, we
+something with it. Remember, in :doc:`Tutorial 3 </intro/tutorial03>`, we
 created a URLconf for the polls application that includes this line::
 
     (r'^(?P<poll_id>\d+)/vote/$', 'vote'),
@@ -149,7 +147,7 @@ This code includes a few things we haven't covered yet in this tutorial:
 
 As mentioned in Tutorial 3, ``request`` is a :class:`~django.http.HttpRequest`
 object. For more on :class:`~django.http.HttpRequest` objects, see the
-:ref:`request and response documentation <ref-request-response>`.
+:doc:`request and response documentation </ref/request-response>`.
 
 After somebody votes in a poll, the ``vote()`` view redirects to the results
 page for the poll. Let's write that view::
@@ -158,8 +156,8 @@ page for the poll. Let's write that view::
         p = get_object_or_404(Poll, pk=poll_id)
         return render_to_response('polls/results.html', {'poll': p})
 
-This is almost exactly the same as the ``detail()`` view from :ref:`Tutorial 3
-<intro-tutorial03>`. The only difference is the template name. We'll fix this
+This is almost exactly the same as the ``detail()`` view from :doc:`Tutorial 3
+</intro/tutorial03>`. The only difference is the template name. We'll fix this
 redundancy later.
 
 Now, create a ``results.html`` template:
@@ -183,7 +181,7 @@ without having chosen a choice, you should see the error message.
 Use generic views: Less code is better
 ======================================
 
-The ``detail()`` (from :ref:`Tutorial 3 <intro-tutorial03>`) and ``results()``
+The ``detail()`` (from :doc:`Tutorial 3 </intro/tutorial03>`) and ``results()``
 views are stupidly simple -- and, as mentioned above, redundant. The ``index()``
 view (also from Tutorial 3), which displays a list of polls, is similar.
 
@@ -328,8 +326,8 @@ are) used multiple times -- but we can use the name we've given::
 
 Run the server, and use your new polling app based on generic views.
 
-For full details on generic views, see the :ref:`generic views documentation
-<topics-http-generic-views>`.
+For full details on generic views, see the :doc:`generic views documentation
+</topics/http/generic-views>`.
 
 Coming soon
 ===========
@@ -344,5 +342,5 @@ will cover:
     * Advanced admin features: Permissions
     * Advanced admin features: Custom JavaScript
 
-In the meantime, you might want to check out some pointers on :ref:`where to go
-from here <intro-whatsnext>`
+In the meantime, you might want to check out some pointers on :doc:`where to go
+from here </intro/whatsnext>`

docs/intro/whatsnext.txt

@@ -1,10 +1,8 @@
-.. _intro-whatsnext:
-
 =================
 What to read next
 =================
 
-So you've read all the :ref:`introductory material <intro-index>` and have
+So you've read all the :doc:`introductory material </intro/index>` and have
 decided you'd like to keep using Django. We've only just scratched the surface
 with this intro (in fact, if you've read every single word you've still read
 less than 10% of the overall documentation).
@@ -37,15 +35,15 @@ How the documentation is organized
 Django's main documentation is broken up into "chunks" designed to fill
 different needs:
 
-    * The :ref:`introductory material <intro-index>` is designed for people new
+    * The :doc:`introductory material </intro/index>` is designed for people new
       to Django -- or to web development in general. It doesn't cover anything
       in depth, but instead gives a high-level overview of how developing in
       Django "feels".
 
-    * The :ref:`topic guides <topics-index>`, on the other hand, dive deep into
+    * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
       individual parts of Django. There are complete guides to Django's
-      :ref:`model system <topics-db-index>`, :ref:`template engine
-      <topics-templates>`, :ref:`forms framework <topics-forms-index>`, and much
+      :doc:`model system </topics/db/index>`, :doc:`template engine
+      </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
       more.
 
       This is probably where you'll want to spend most of your time; if you work
@@ -53,27 +51,27 @@ different needs:
       everything there is to know about Django.
 
     * Web development is often broad, not deep -- problems span many domains.
-      We've written a set of :ref:`how-to guides <howto-index>` that answer
+      We've written a set of :doc:`how-to guides </howto/index>` that answer
       common "How do I ...?" questions. Here you'll find information about
-      :ref:`generating PDFs with Django <howto-outputting-pdf>`, :ref:`writing
-      custom template tags <howto-custom-template-tags>`, and more.
+      :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
+      custom template tags </howto/custom-template-tags>`, and more.
 
-      Answers to really common questions can also be found in the :ref:`FAQ
-      <faq-index>`.
+      Answers to really common questions can also be found in the :doc:`FAQ
+      </faq/index>`.
 
     * The guides and how-to's don't cover every single class, function, and
       method available in Django -- that would be overwhelming when you're
       trying to learn. Instead, details about individual classes, functions,
-      methods, and modules are kept in the :ref:`reference <ref-index>`. This is
+      methods, and modules are kept in the :doc:`reference </ref/index>`. This is
       where you'll turn to find the details of a particular function or
       whathaveyou.
 
     * Finally, there's some "specialized" documentation not usually relevant to
-      most developers. This includes the :ref:`release notes <releases-index>`,
-      :ref:`documentation of obsolete features <obsolete-index>`,
-      :ref:`internals documentation <internals-index>` for those who want to add
-      code to Django itself, and a :ref:`few other things that simply don't fit
-      elsewhere <misc-index>`.
+      most developers. This includes the :doc:`release notes </releases/index>`,
+      :doc:`documentation of obsolete features </obsolete/index>`,
+      :doc:`internals documentation </internals/index>` for those who want to add
+      code to Django itself, and a :doc:`few other things that simply don't fit
+      elsewhere </misc/index>`.
 
 
 How documentation is updated

docs/misc/api-stability.txt

@@ -1,10 +1,8 @@
-.. _misc-api-stability:
-
 =============
 API stability
 =============
 
-: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.
@@ -37,67 +35,67 @@ Stable APIs
 ===========
 
 In general, everything covered in the documentation -- with the exception of
-anything in the :ref:`internals area <internals-index>` is considered stable as
+anything in the :doc:`internals area </internals/index>` is considered stable as
 of 1.0. This includes these APIs:
 
-    - :ref:`Authorization <topics-auth>`
+    - :doc:`Authorization </topics/auth>`
 
-    - :ref:`Caching <topics-cache>`.
+    - :doc:`Caching </topics/cache>`.
     
-    - :ref:`Model definition, managers, querying and transactions
-      <topics-db-index>`
+    - :doc:`Model definition, managers, querying and transactions
+      </topics/db/index>`
     
-    - :ref:`Sending e-mail <topics-email>`.
+    - :doc:`Sending e-mail </topics/email>`.
     
-    - :ref:`File handling and storage <topics-files>`
+    - :doc:`File handling and storage </topics/files>`
     
-    - :ref:`Forms <topics-forms-index>`
+    - :doc:`Forms </topics/forms/index>`
     
-    - :ref:`HTTP request/response handling <topics-http-index>`, including file
+    - :doc:`HTTP request/response handling </topics/http/index>`, including file
       uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
     
-    - :ref:`Generic views <topics-http-generic-views>`.
+    - :doc:`Generic views </topics/http/generic-views>`.
 
-    - :ref:`Internationalization <topics-i18n>`.
+    - :doc:`Internationalization </topics/i18n/index>`.
     
-    - :ref:`Pagination <topics-pagination>`
+    - :doc:`Pagination </topics/pagination>`
     
-    - :ref:`Serialization <topics-serialization>`
+    - :doc:`Serialization </topics/serialization>`
     
-    - :ref:`Signals <topics-signals>`
+    - :doc:`Signals </topics/signals>`
     
-    - :ref:`Templates <topics-templates>`, including the language, Python-level
-      :ref:`template APIs <ref-templates-index>`, and :ref:`custom template tags
-      and libraries <howto-custom-template-tags>`. We may add new template
+    - :doc:`Templates </topics/templates>`, including the language, Python-level
+      :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags
+      and libraries </howto/custom-template-tags>`. We may add new template
       tags in the future and the names may inadvertently clash with
       external template tags. Before adding any such tags, we'll ensure that
       Django raises an error if it tries to load tags with duplicate names.
       
-    - :ref:`Testing <topics-testing>`
+    - :doc:`Testing </topics/testing>`
 
-    - :ref:`django-admin utility <ref-django-admin>`.
+    - :doc:`django-admin utility </ref/django-admin>`.
     
-    - :ref:`Built-in middleware <ref-middleware>`
+    - :doc:`Built-in middleware </ref/middleware>`
     
-    - :ref:`Request/response objects <ref-request-response>`.
+    - :doc:`Request/response objects </ref/request-response>`.
     
-    - :ref:`Settings <ref-settings>`. Note, though that while the :ref:`list of
-      built-in settings <ref-settings>` can be considered complete we may -- and
+    - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of
+      built-in settings </ref/settings>` can be considered complete we may -- and
       probably will -- add new settings in future versions. This is one of those
       places where "'stable' does not mean 'complete.'"
       
-    - :ref:`Built-in signals <ref-signals>`. Like settings, we'll probably add
+    - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add
       new signals in the future, but the existing ones won't break.
       
-    - :ref:`Unicode handling <ref-unicode>`.
+    - :doc:`Unicode handling </ref/unicode>`.
         
-    - Everything covered by the :ref:`HOWTO guides <howto-index>`.
+    - Everything covered by the :doc:`HOWTO guides </howto/index>`.
     
 ``django.utils``
 ----------------
 
 Most of the modules in ``django.utils`` are designed for internal use. Only
-the following parts of :ref:`django.utils <ref-utils>` can be considered stable:
+the following parts of :doc:`django.utils </ref/utils>` can be considered stable:
 
     - ``django.utils.cache``
     - ``django.utils.datastructures.SortedDict`` -- only this single class; the

docs/misc/design-philosophies.txt

@@ -1,5 +1,3 @@
-.. _misc-design-philosophies:
-
 ===================
 Design philosophies
 ===================

docs/misc/distributions.txt

@@ -1,5 +1,3 @@
-.. _misc-distributions:
-
 ===================================
 Third-party distributions of Django
 ===================================

docs/misc/index.txt

@@ -1,5 +1,3 @@
-.. _misc-index:
-
 Meta-documentation and miscellany
 =================================
 

docs/obsolete/admin-css.txt

@@ -1,5 +1,3 @@
-.. _obsolete-admin-css:
-
 ======================================
 Customizing the Django admin interface
 ======================================

docs/obsolete/index.txt

@@ -1,5 +1,3 @@
-.. _obsolete-index:
-
 Deprecated/obsolete documentation
 =================================
 

docs/ref/authbackends.txt

@@ -1,5 +1,3 @@
-.. _ref-authentication-backends:
-
 =======================
 Authentication backends
 =======================
@@ -10,8 +8,8 @@ Authentication backends
 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 :ref:`User authentication guide
-<topics-auth>`.
+<authentication-backends>` of the :doc:`User authentication guide
+</topics/auth>`.
 
 
 Available authentication backends
@@ -33,5 +31,5 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     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 :ref:`Authenticating against REMOTE_USER <howto-auth-remote-user>`
+    the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
     documentation.

docs/ref/contrib/admin/actions.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-admin-actions:
-
 =============
 Admin actions
 =============
@@ -208,7 +206,7 @@ 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
-:ref:`serialization functions <topics-serialization>` to dump some selected
+:doc:`serialization functions </topics/serialization>` to dump some selected
 objects as JSON::
 
     from django.http import HttpResponse

docs/ref/contrib/admin/index.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-admin:
-
 =====================
 The Django admin site
 =====================
@@ -678,7 +676,7 @@ do that::
 
 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 :ref:`ref-forms-api` for details.
+:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for details.
 
 .. warning::
 
@@ -696,7 +694,7 @@ The value is another dictionary; these arguments will be passed to
 .. versionadded:: 1.1
 
 A list of actions to make available on the change list page. See
-:ref:`ref-contrib-admin-actions` for details.
+:doc:`/ref/contrib/admin/actions` for details.
 
 .. attribute:: ModelAdmin.actions_on_top
 .. attribute:: ModelAdmin.actions_on_bottom
@@ -747,8 +745,8 @@ templates used by the :class:`ModelAdmin` views:
 
     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 :ref:`actions
-    documentation<ref-contrib-admin-actions>`.
+    or more objects. See the :doc:`actions
+    documentation</ref/contrib/admin/actions>`.
 
 .. attribute:: ModelAdmin.object_history_template
 
@@ -805,7 +803,7 @@ described above in the :attr:`ModelAdmin.readonly_fields` section.
 
 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 :ref:`topics-http-urls`::
+documented in :doc:`/topics/http/urls`::
 
     class MyModelAdmin(admin.ModelAdmin):
         def get_urls(self):
@@ -969,7 +967,7 @@ on your ``ModelAdmin``::
             js = ("my_code.js",)
 
 Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules
-apply as :ref:`regular media definitions on forms <topics-forms-media>`.
+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
@@ -1002,8 +1000,8 @@ any field::
             return self.cleaned_data["name"]
 
 It is important you use a ``ModelForm`` here otherwise things can break. See the
-:ref:`forms <ref-forms-index>` documentation on :ref:`custom validation
-<ref-forms-validation>` and, more specifically, 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.
 
@@ -1075,7 +1073,7 @@ all the same functionality as well as some of its own:
 
     This controls the number of extra forms the formset will display in addition
     to the initial forms. See the
-    :ref:`formsets documentation <topics-forms-formsets>` for more information.
+    :doc:`formsets documentation </topics/forms/formsets>` for more information.
 
     .. versionadded:: 1.2
 
@@ -1298,7 +1296,7 @@ example app::
 
 ``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline``
 and ``GenericStackedInline`` and behave just like any other inline. See the
-:ref:`contenttypes documentation <ref-contrib-contenttypes>` for more specific
+:doc:`contenttypes documentation </ref/contrib/contenttypes>` for more specific
 information.
 
 Overriding Admin Templates

docs/ref/contrib/auth.txt

@@ -1,6 +1,4 @@
-.. _ref-contrib-auth:
-
 ``django.contrib.auth``
 =======================
 
-See :ref:`topics-auth`.
+See :doc:`/topics/auth`.

docs/ref/contrib/comments/custom.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-custom:
-
 ==================================
 Customizing the comments framework
 ==================================

docs/ref/contrib/comments/example.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-example:
-
 .. highlightlang:: html+django
 
 ===========================================
@@ -7,7 +5,7 @@ Example of using the in-built comments app
 ===========================================
 
 Follow the first three steps of the quick start guide in the
-:ref:`documentation <ref-contrib-comments-index>`.
+: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
@@ -85,8 +83,8 @@ It looks for the ``form.html`` under the following directories
 
 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 :ref:`customization
-<ref-contrib-comments-custom>`, :ttag:`comment_form_target` evaluates to
+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
@@ -136,7 +134,7 @@ found under the directory structure we saw for ``form.html``.
 Feeds
 =====
 
-Suppose you want to export a :ref:`feed <ref-contrib-syndication>` of the
+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``:
 
@@ -163,8 +161,8 @@ 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 :ref:`generic comment moderation
-<ref-contrib-comments-moderation>`. The comment moderation has the following
+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.
@@ -181,18 +179,18 @@ following way:
 
    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.

docs/ref/contrib/comments/forms.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-forms:
-
 ====================
 Comment form classes
 ====================
@@ -9,7 +7,7 @@ Comment form classes
 
 The ``django.contrib.comments.forms`` module contains a handful of forms
 you'll use when writing custom views dealing with comments, or when writing
-:ref:`custom comment apps <ref-contrib-comments-custom>`.
+:doc:`custom comment apps </ref/contrib/comments/custom>`.
 
 .. class:: CommentForm
 
@@ -23,7 +21,7 @@ you'll use when writing custom views dealing with comments, or when writing
 Abstract comment forms for custom comment apps
 ----------------------------------------------
 
-If you're building a :ref:`custom comment app <ref-contrib-comments-custom>`,
+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.
 

docs/ref/contrib/comments/index.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-index:
-
 ===========================
 Django's comments framework
 ===========================
@@ -16,7 +14,7 @@ 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 :ref:`upgrade guide <ref-contrib-comments-upgrade>`
+    need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>`
     for instructions.
 
 Quick start guide
@@ -42,7 +40,7 @@ To get started using the ``comments`` app, follow these steps:
     #. Use the `comment template tags`_ below to embed comments in your
        templates.
 
-You might also want to examine :ref:`ref-contrib-comments-settings`.
+You might also want to examine :doc:`/ref/contrib/comments/settings`.
 
 Comment template tags
 =====================
@@ -124,7 +122,7 @@ For example::
     {% endfor %}
 
 This returns a list of :class:`~django.contrib.comments.models.Comment` objects;
-see :ref:`the comment model documentation <ref-contrib-comments-models>` for
+see :doc:`the comment model documentation </ref/contrib/comments/models>` for
 details.
 
 .. templatetag:: get_comment_permalink
@@ -212,7 +210,7 @@ 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 :ref:`form object <topics-forms-index>` that
+: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] %}
@@ -279,8 +277,8 @@ should know about:
       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 :ref:`Cross Site Request
-Forgery protection < ref-contrib-csrf>` that comes with Django.  As described in
+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

docs/ref/contrib/comments/models.txt

@@ -1,82 +1,80 @@
-.. _ref-contrib-comments-models:
-
 ===========================
 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
-        :ref:`ref-contrib-comments-moderation`); If ``True``, the comment will
+        :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.
-        
+

docs/ref/contrib/comments/moderation.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-moderation:
-
 ==========================
 Generic comment moderation
 ==========================

docs/ref/contrib/comments/settings.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-settings:
-
 ================
 Comment settings
 ================
@@ -29,7 +27,7 @@ this will be rejected. Defaults to 3000.
 COMMENTS_APP
 ------------
 
-An app which provides :ref:`customization of the comments framework
-<ref-contrib-comments-custom>`.  Use the same dotted-string notation
+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`.

docs/ref/contrib/comments/signals.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-signals:
-
 ================================
 Signals sent by the comments app
 ================================
@@ -7,9 +5,9 @@ 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 :ref:`signals <topics-signals>` to allow for
-comment moderation and similar activities. See :ref:`the introduction to signals
-<topics-signals>` for information about how to register for and receive these
+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

docs/ref/contrib/comments/upgrade.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-comments-upgrade:
-
 ===============================================
 Upgrading from Django's previous comment system
 ===============================================
@@ -11,8 +9,8 @@ The main changes from the old system are:
 
     * This new system is documented.
     
-    * It uses modern Django features like :ref:`forms <topics-forms-index>` and
-      :ref:`modelforms <topics-forms-modelforms>`.
+    * 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.
@@ -42,7 +40,7 @@ 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
-:ref:`quick start guide <ref-contrib-comments-index>`.
+: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

docs/ref/contrib/contenttypes.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-contenttypes:
-
 ==========================
 The contenttypes framework
 ==========================
@@ -346,7 +344,7 @@ it would be deleted at the same time.
 Generic relations and aggregation
 ---------------------------------
 
-:ref:`Django's database aggregation API <topics-db-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::
@@ -365,8 +363,8 @@ Generic relations in forms and admin
 :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
-:ref:`model formset <topics-forms-modelforms>` and
-:ref:`admin <ref-contrib-admin>` documentation for more information.
+:doc:`model formset </topics/forms/modelforms>` and
+:doc:`admin </ref/contrib/admin/index>` documentation for more information.
 
 .. class:: generic.GenericInlineModelAdmin
 

docs/ref/contrib/csrf.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-csrf:
-
 =====================================
 Cross Site Request Forgery protection
 =====================================

docs/ref/contrib/databrowse.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-databrowse:
-
 ==========
 Databrowse
 ==========
@@ -49,8 +47,8 @@ How to use Databrowse
        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 :ref:`URLconf file
-       <topics-http-urls>` (``urls.py``).
+       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::
 
@@ -73,20 +71,20 @@ code. Simply add the following import to your URLconf::
 
     from django.contrib.auth.decorators import login_required
 
-Then modify the :ref:`URLconf <topics-http-urls>` so that the
+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 :ref:`URLconf
-<topics-http-urls>`, as described in the :ref:`user authentication docs
-<ref-contrib-auth>`, then you will need to do so now with the following
+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
-:ref:`user authentication docs <ref-contrib-auth>` provide full details and a
+:doc:`user authentication docs </ref/contrib/auth>` provide full details and a
 sample template that can be used for this purpose.

docs/ref/contrib/flatpages.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-flatpages:
-
 =================
 The flatpages app
 =================
@@ -92,8 +90,8 @@ 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 :ref:`middleware docs
-<topics-http-middleware>`.
+For more on middleware, read the :doc:`middleware docs
+</topics/http/middleware>`.
 
 .. admonition:: Ensure that your 404 template works
     
@@ -124,9 +122,9 @@ Via the Python API
 .. class:: models.FlatPage
 
     Flatpages are represented by a standard
-    :ref:`Django model <topics-db-models>`,
+    :doc:`Django model </topics/db/models>`,
     which lives in `django/contrib/flatpages/models.py`_. You can access
-    flatpage objects via the :ref:`Django database API <topics-db-queries>`.
+    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
 

docs/ref/contrib/formtools/form-preview.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-formtools-form-preview:
-
 ============
 Form preview
 ============

docs/ref/contrib/formtools/form-wizard.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-formtools-form-wizard:
-
 ===========
 Form wizard
 ===========
@@ -10,7 +8,7 @@ Form wizard
 .. versionadded:: 1.0
 
 Django comes with an optional "form wizard" application that splits
-:ref:`forms <topics-forms-index>` across multiple Web pages. It maintains
+: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.
 
@@ -65,8 +63,8 @@ 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 :ref:`forms documentation
-<topics-forms-index>`.  These classes can live anywhere in your codebase, but
+: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.
 

docs/ref/contrib/formtools/index.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-formtools-index:
-
 django.contrib.formtools
 ========================
 

docs/ref/contrib/gis/admin.txt

@@ -54,7 +54,7 @@ GeoDjango's admin site
    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

docs/ref/contrib/gis/commands.txt

@@ -78,6 +78,6 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
    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.

docs/ref/contrib/gis/db-api.txt

@@ -14,7 +14,7 @@ Spatial Backends
 
 .. versionadded:: 1.2
 
-In Django 1.2, support for :ref:`multiple databases <topics-db-multi-db>` was
+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:
 
@@ -26,7 +26,7 @@ its functionality into full-fledged spatial database backends:
 Database Settings Backwards-Compatibility
 -----------------------------------------
 
-In :ref:`Django 1.2 <releases-1.2>`, the way 
+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
@@ -60,7 +60,7 @@ MySQL's spatial extensions only support bounding box operations
     [``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. 
+    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
@@ -92,8 +92,8 @@ model)::
     >>> 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 
+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'
@@ -133,17 +133,17 @@ 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 
+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 
+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 
+    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`.
 
@@ -156,8 +156,8 @@ 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 
+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:
@@ -181,7 +181,7 @@ The following distance lookups are available:
 
 Distance lookups take a tuple parameter comprising:
 
-#. A geometry to base calculations from; and 
+#. 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,
@@ -191,8 +191,8 @@ 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 
+    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
@@ -212,24 +212,24 @@ to be in the units of the field.
     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 
+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!) 
+        # A projected coordinate system (only valid for South Texas!)
         # is used, units are in meters.
-        point = models.PointField(srid=32140) 
+        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 
+    >>> 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.
@@ -294,7 +294,7 @@ Lookup Type                        PostGIS    Oracle    MySQL [#]_   SpatiaLite
 ``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 
+are available on each spatial backend.  Please note that MySQL does not
 support any of these methods, and is thus excluded from the table.
 
 ====================================  =======  ======  ==========
@@ -330,7 +330,7 @@ Method                                PostGIS  Oracle  SpatiaLite
 :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).

docs/ref/contrib/gis/deployment.txt

@@ -54,7 +54,7 @@ Example::
     number of ``processes`` instead.
 
 For more information, please consult Django's
-:ref:`mod_wsgi documentation <howto-deployment-modwsgi>`.
+:doc:`mod_wsgi documentation </howto/deployment/modwsgi>`.
 
 ``mod_python``
 --------------
@@ -84,7 +84,7 @@ Example::
    else your GeoDjango application may crash Apache.
 
 For more information, please consult Django's
-:ref:`mod_python documentation <howto-deployment-modpython>`.
+:doc:`mod_python documentation </howto/deployment/modpython>`.
 
 Lighttpd
 ========

docs/ref/contrib/gis/feeds.txt

@@ -1,5 +1,3 @@
-.. _ref-gis-feeds:
-
 ================
 Geographic Feeds
 ================
@@ -8,10 +6,10 @@ Geographic 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 
+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 `Django's syndication documentation <ref-contrib-syndication>`
-for details on general usage.
+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/
 
@@ -28,7 +26,7 @@ API Reference
 
 .. class:: Feed
 
-   In addition to methods provided by 
+   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::

docs/ref/contrib/gis/geoquerysets.txt

@@ -14,12 +14,12 @@ GeoQuerySet API Reference
 Spatial Lookups
 ===============
 
-Just like when using the the :ref:`queryset-api`, interaction 
+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 
+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>`.
@@ -31,7 +31,7 @@ bbcontains
 
 *Availability*: PostGIS, MySQL, SpatiaLite
 
-Tests if the geometry field's bounding box completely contains the lookup 
+Tests if the geometry field's bounding box completely contains the lookup
 geometry's bounding box.
 
 Example::
@@ -53,7 +53,7 @@ bboverlaps
 
 *Availability*: PostGIS, MySQL, SpatiaLite
 
-Tests if the geometry field's bounding box overlaps the lookup geometry's 
+Tests if the geometry field's bounding box overlaps the lookup geometry's
 bounding box.
 
 Example::
@@ -277,9 +277,9 @@ the values given in the given pattern.  This lookup requires a tuple parameter,
 
 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.  
+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]_
@@ -302,7 +302,7 @@ Oracle
 ~~~~~~
 
 Here the relation pattern is compreised at least one of the nine relation
-strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, 
+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
@@ -312,7 +312,7 @@ Example::
 
     Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
 
-Oracle SQL equivalent:: 
+Oracle SQL equivalent::
 
     SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
 
@@ -403,7 +403,7 @@ overlaps_left
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box overlaps or is to the left of the lookup 
+Tests if the geometry field's bounding box overlaps or is to the left of the lookup
 geometry's bounding box.
 
 Example::
@@ -422,7 +422,7 @@ overlaps_right
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box overlaps or is to the right of the lookup 
+Tests if the geometry field's bounding box overlaps or is to the right of the lookup
 geometry's bounding box.
 
 Example::
@@ -440,7 +440,7 @@ overlaps_above
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box overlaps or is above the lookup 
+Tests if the geometry field's bounding box overlaps or is above the lookup
 geometry's bounding box.
 
 Example::
@@ -458,7 +458,7 @@ overlaps_below
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box overlaps or is below the lookup 
+Tests if the geometry field's bounding box overlaps or is below the lookup
 geometry's bounding box.
 
 Example::
@@ -476,7 +476,7 @@ strictly_above
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box is strictly above the lookup 
+Tests if the geometry field's bounding box is strictly above the lookup
 geometry's bounding box.
 
 Example::
@@ -494,7 +494,7 @@ strictly_below
 
 *Availability*: PostGIS
 
-Tests if the geometry field's bounding box is strictly above the lookup 
+Tests if the geometry field's bounding box is strictly above the lookup
 geometry's bounding box.
 
 Example::
@@ -662,7 +662,7 @@ 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 
+                       keyword should be used to specify another
                        geographic field (e.g., ``field_name='point2'``)
                        when there are multiple geographic fields in a model.
 
@@ -670,7 +670,7 @@ Keyword Argument       Description
                        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
@@ -679,12 +679,12 @@ Keyword Argument       Description
                        ``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.  
+                       ``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`` 
+                       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.
 =====================  =====================================================
 
@@ -705,12 +705,12 @@ each element of this GeoQuerySet.
 
 .. 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 
+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 
+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
@@ -732,7 +732,7 @@ the distance from the `Tasmanian`__ city of Hobart to every other
     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 
+    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`.
 
@@ -867,9 +867,9 @@ then 4326 (WGS84) is used by default.
     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 
+
+    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::
@@ -903,7 +903,7 @@ to each element of the ``GeoQuerySet`` that is the result of the operation.
 .. 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 
+geometry in a ``difference`` attribute on each element of the
 ``GeoQuerySet``.
 
 
@@ -913,7 +913,7 @@ geometry in a ``difference`` attribute on each element of the
 .. 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 
+given geometry in an ``intersection`` attribute on each element of the
 ``GeoQuerySet``.
 
 ``sym_difference``
@@ -937,7 +937,7 @@ geometry in an ``union`` attribute on each element of the
 Geometry Output
 ---------------
 
-The following ``GeoQuerySet`` methods will return an attribute that has the value 
+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``
@@ -967,8 +967,8 @@ Attaches a ``geojson`` attribute to every model in the queryset that contains th
 =====================  =====================================================
 Keyword Argument       Description
 =====================  =====================================================
-``precision``          It may be used to specify the number of significant 
-                       digits for the coordinates in the GeoJSON 
+``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
@@ -988,8 +988,8 @@ __ http://geojson.org/
 
 *Availability*: PostGIS, Oracle
 
-Attaches a ``gml`` attribute to every model in the queryset that contains the 
-`Geographic Markup Language (GML)`__ representation of the geometry. 
+Attaches a ``gml`` attribute to every model in the queryset that contains the
+`Geographic Markup Language (GML)`__ representation of the geometry.
 
 Example::
 
@@ -1000,9 +1000,9 @@ Example::
 =====================  =====================================================
 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 
+``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
@@ -1019,9 +1019,9 @@ __ http://en.wikipedia.org/wiki/Geography_Markup_Language
 
 *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 
+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::
@@ -1033,8 +1033,8 @@ Example::
 =====================  =====================================================
 Keyword Argument       Description
 =====================  =====================================================
-``precision``          This keyword may be used to specify the number of 
-                       significant digits for the coordinates in the KML 
+``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.
 =====================  =====================================================
 
@@ -1054,11 +1054,11 @@ 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``, 
+                       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 
+``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.
 =====================  =====================================================
 
@@ -1129,7 +1129,7 @@ dissolving boundaries.
 
 *Availability*: PostGIS, Oracle
 
-Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the 
+Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the
 lower left coordinate and the upper right coordinate.
 
 Example::
@@ -1163,7 +1163,7 @@ Example::
 
 *Availability*: PostGIS
 
-Returns a ``LineString`` constructed from the point field geometries in the 
+Returns a ``LineString`` constructed from the point field geometries in the
 ``GeoQuerySet``.  Currently, ordering the queryset has no effect.
 
 Example::
@@ -1184,25 +1184,25 @@ 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``          This keyword is for Oracle only.  It is for the
                        tolerance value used by the ``SDOAGGRTYPE``
-                       procedure; the  `Oracle documentation`__ has more 
+                       procedure; the  `Oracle documentation`__ has more
                        details.
 =====================  =====================================================
 
-__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 
+__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
 
 Aggregate Functions
 -------------------

docs/ref/contrib/gis/install.txt

@@ -13,7 +13,7 @@ In general, GeoDjango installation requires:
 3. :ref:`geospatial_libs`
 
 Details for each of the requirements and installation instructions
-are provided in the sections below.   In addition, platform-specific 
+are provided in the sections below.   In addition, platform-specific
 instructions are available for:
 
 * :ref:`macosx`
@@ -23,10 +23,10 @@ instructions are available for:
 .. 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.  
+    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 
+    may be required. When compiling the libraries from source, please follow the
     directions closely, especially if you're a beginner.
 
 Requirements
@@ -37,8 +37,8 @@ Requirements
 Python 2.4+
 -----------
 Because of heavy use of the decorator syntax, Python 2.4 is minimum
-version supported by GeoDjango. Python 2.5+ is recommended because the 
-`ctypes`__ module comes included; otherwise, 2.4 users will need to 
+version supported by GeoDjango. 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
@@ -50,18 +50,18 @@ Django
 ------
 
 Because GeoDjango is included with Django, please refer to Django's
-:ref:`installation instructions <intro-install>` for details on how to install.
+: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 
+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 
+    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
@@ -81,7 +81,7 @@ SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.6.+               Requires
 
 Geospatial Libraries
 --------------------
-GeoDjango uses and/or provides interfaces for the the following open source 
+GeoDjango uses and/or provides interfaces for the the following open source
 geospatial libraries:
 
 ========================  ====================================  ================================  ==========================
@@ -117,7 +117,7 @@ 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 
+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.
 
@@ -147,13 +147,13 @@ 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 website and untar the source 
+First, download GEOS 3.2 from the refractions website 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 
+Next, change into the directory where GEOS was unpacked, run the configure
 script, compile, and install::
 
     $ cd geos-3.2.2
@@ -172,7 +172,7 @@ 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 
+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`.
@@ -191,7 +191,7 @@ C library.  For example::
 
 .. note::
 
-    The setting must be the *full* path to the **C** shared library; in 
+    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:
@@ -199,7 +199,7 @@ C library.  For example::
 PROJ.4
 ------
 
-`PROJ.4`_ is a library for converting geospatial data to different coordinate 
+`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 [#]_::
@@ -228,12 +228,12 @@ PostGIS
 -------
 
 `PostGIS`__ adds geographic object support to PostgreSQL, turning it
-into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be 
+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 
+    The `psycopg2`_ module is required for use as the database adaptor
     when using GeoDjango with PostGIS.
 
 .. _psycopg2: http://initd.org/projects/psycopg2
@@ -256,7 +256,7 @@ Finally, make and install::
 
 .. note::
 
-    GeoDjango does not automatically create a spatial database.  Please 
+    GeoDjango does not automatically create a spatial database.  Please
     consult the section on :ref:`spatialdb_template` for more information.
 
 __ http://postgis.refractions.net/
@@ -267,7 +267,7 @@ GDAL
 ----
 
 `GDAL`__ is an excellent open source geospatial library that has support for
-reading most vector and raster spatial data formats.  Currently, GeoDjango only 
+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.
 
@@ -287,11 +287,11 @@ Configure, make and install::
 .. 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 
+   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. 
+   `GDAL/OGR In Python`__ for more information on GDAL's bindings.
 
-If you have any problems, please see the troubleshooting section below for 
+If you have any problems, please see the troubleshooting section below for
 suggestions and solutions.
 
 __ http://trac.osgeo.org/gdal/
@@ -312,7 +312,7 @@ will be false::
     >>> gdal.HAS_GDAL
     False
 
-The solution is to properly configure your :ref:`libsettings` *or* set 
+The solution is to properly configure your :ref:`libsettings` *or* set
 :ref:`gdallibrarypath` in your settings.
 
 .. _gdallibrarypath:
@@ -332,22 +332,22 @@ the GDAL library.  For example::
 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 
+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 
+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 
+If using Apache, you may need to add this environment variable to your configuration
 file::
 
     SetEnv GDAL_DATA /usr/local/share
@@ -363,13 +363,13 @@ SpatiaLite
    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 
+`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 
+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 
+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
@@ -380,7 +380,7 @@ 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 
+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
@@ -398,7 +398,7 @@ needs to be customized so that SQLite knows to build the R*Tree module::
 .. 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 
+    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.
@@ -420,7 +420,7 @@ SpatiaLite library source and tools bundle from the `download page`__::
     $ 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 
+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
@@ -431,7 +431,7 @@ customization of the ``configure`` command is necessary.  If not, then run the
 
 Finally, do the same for the SpatiaLite tools::
 
-    $ cd spatialite-tools-2.3.1   
+    $ cd spatialite-tools-2.3.1
     $ ./configure # May need to modified, see notes below.
     $ make
     $ sudo make install
@@ -440,15 +440,15 @@ Finally, do the same for the SpatiaLite tools::
 .. 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, 
+    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 
+    For Mac OS X users building from source, the SpatiaLite library *and* tools
     need to have their ``target`` configured::
 
         $ ./configure --target=macosx
@@ -463,7 +463,7 @@ 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
@@ -484,7 +484,7 @@ to look like the following::
     ``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.   
+    and ``/usr/lib``, respectively.
 
 After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script
 to build and install::
@@ -500,7 +500,7 @@ 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 
+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.
 
@@ -518,7 +518,7 @@ user.  For example, you can use the following to become the ``postgres`` user::
    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 
+   ``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
@@ -598,7 +598,7 @@ __ 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 
+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.
@@ -630,7 +630,7 @@ Invoke the Django shell from your project and execute the
     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 
+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
@@ -640,8 +640,8 @@ 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 
+  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
@@ -659,7 +659,7 @@ 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 
+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
@@ -670,9 +670,9 @@ system.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A user may set this environment variable to customize the library paths
-they want to use.  The typical library directory for software 
+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 
+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
@@ -682,7 +682,7 @@ 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  
+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
@@ -702,9 +702,9 @@ 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 
+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 
+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
@@ -735,10 +735,10 @@ several different options for installing GeoDjango.  These options are:
 .. note::
 
     Currently, the easiest and recommended approach for installing GeoDjango
-    on OS X is to use the KyngChaos packages.  
+    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 
+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:
@@ -747,8 +747,8 @@ 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 
+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.
 
@@ -756,7 +756,7 @@ __ 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::
@@ -768,15 +768,15 @@ __ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
 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 
+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).  
+and :ref:`pysqlite2_kyngchaos` (for SpatiaLite).
 
 .. note::
 
-    SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section 
+    SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section
     after installing the packages for additional instructions.
 
 Download the framework packages for:
@@ -834,7 +834,7 @@ described above, ``psycopg2`` may be installed using the following command::
 pysqlite2
 ~~~~~~~~~
 
-Follow the :ref:`pysqlite2` source install instructions, however, 
+Follow the :ref:`pysqlite2` source install instructions, however,
 when editing the ``setup.cfg`` use the following instead::
 
     [build_ext]
@@ -851,7 +851,7 @@ 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 
+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
@@ -887,9 +887,9 @@ __ http://www.finkproject.org/
 MacPorts
 ^^^^^^^^
 
-`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh 
+`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. 
+the `Apple Developer Tools`_ are required.
 
 Summary::
 
@@ -898,7 +898,7 @@ Summary::
     $ sudo port install proj
     $ sudo port install postgis
     $ sudo port install gdal
-    $ sudo port install libgeoip  
+    $ sudo port install libgeoip
 
 .. note::
 
@@ -929,9 +929,9 @@ Ubuntu
 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 
+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.
@@ -970,11 +970,11 @@ Optional packages to consider:
 * ``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 
+    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 
+    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
@@ -985,7 +985,7 @@ Optional packages to consider:
         $ 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 
+    do not plan on doing any database transformation of geometries to the
     Google projection (900913).
 
 .. note::
@@ -1032,14 +1032,14 @@ Optional packages:
 Source Packages
 ~~~~~~~~~~~~~~~
 You will still have to install :ref:`geosbuild`, :ref:`proj4`,
-:ref:`postgis`, and :ref:`gdalbuild` from source.  Please follow the 
+: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 
+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
@@ -1086,13 +1086,13 @@ Python
 ^^^^^^
 
 First, download the `Python 2.6 installer`__ from the Python website.  Next,
-execute the installer and use defaults, e.g., keep 'Install for all users' 
+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 
+    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
@@ -1107,21 +1107,21 @@ the EnterpriseDB website.
 
    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 
+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 -> 
+    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 
+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
@@ -1132,22 +1132,22 @@ __ 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, 
+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 
+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 
+    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 
+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
@@ -1160,31 +1160,31 @@ 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 
+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 
+    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 
+    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.  
+       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/>`_ 
+       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.

docs/ref/contrib/gis/layermapping.txt

@@ -14,7 +14,7 @@ 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 
+a vector layer, converting to another coordinate system (e.g. WGS84), and
 then inserting into a GeoDjango model.
 
 .. note::
@@ -27,7 +27,7 @@ then inserting into a GeoDjango model.
     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 
+    *every* SQL query -- thus, when SQL statements contain geometries, it is
     easy to consume more memory than is typical.
 
 Example
@@ -50,7 +50,7 @@ Example
         DATUM["WGS_1984",
             SPHEROID["WGS_1984",6378137,298.257223563]],
         PRIMEM["Greenwich",0],
-        UNIT["Degree",0.017453292519943295]]    
+        UNIT["Degree",0.017453292519943295]]
 
 2. Now we define our corresponding Django model (make sure to use ``syncdb``)::
 
@@ -71,16 +71,16 @@ Example
     >>> 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. 
+    >>> 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 
+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
@@ -106,43 +106,43 @@ Argument           Description
                    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 
+=====================  =====================================================
+``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` 
+
+``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 
+
+``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 
+
+``transaction_mode``   May be ``'commit_on_success'`` (default) or
                        ``'autocommit'``.
-    
-``transform``          Setting this to False will disable coordinate 
+
+``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 
+                       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
 ----------------------------
@@ -156,42 +156,42 @@ 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 
+``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 
+                             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, 
+                             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 
+                             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 
+``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 
+``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 
+``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 
+``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 
+``verbose``                  If set, information will be printed
+                             subsequent to each model save
                              executed on the database.
 ===========================  =================================================
 
@@ -213,7 +213,7 @@ 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 
+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::
 

docs/ref/contrib/gis/measure.txt

@@ -7,17 +7,17 @@ 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 
+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 
+: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
@@ -40,7 +40,7 @@ Moreover, arithmetic operations may be performed between the distance
 objects::
 
     >>> print d1 + d2 # Adding 5 miles to 5 kilometers
-    13.04672 km    
+    13.04672 km
     >>> print d2 - d1 # Subtracting 5 kilometers from 5 miles
     1.89314403881 mi
 
@@ -67,7 +67,7 @@ Supported units
 =================================  ========================================
 Unit Attribute                     Full name or alias(es)
 =================================  ========================================
-``km``                             Kilometre, Kilometer   
+``km``                             Kilometre, Kilometer
 ``mi``                             Mile
 ``m``                              Meter, Metre
 ``yd``                             Yard
@@ -163,7 +163,7 @@ Measurement API
        12.949940551680001
 
    .. classmethod:: unit_attname(unit_name)
-   
+
    Returns the area unit attribute name for the given full unit name.
    For example::
 
@@ -175,6 +175,6 @@ Measurement API
    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/>`_ 
+.. [#] `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.

docs/ref/contrib/gis/model-api.txt

@@ -8,11 +8,11 @@ GeoDjango Model API
    :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 
+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()
@@ -23,7 +23,7 @@ __ http://en.wikipedia.org/wiki/ZIP_code
 Geometry Field Types
 ====================
 
-Each of the following geometry field types correspond with the 
+Each of the following geometry field types correspond with the
 OpenGIS Simple Features specification [#fnogc]_.
 
 ``GeometryField``
@@ -92,7 +92,7 @@ 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 
+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
@@ -105,7 +105,7 @@ 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., 
+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
@@ -113,12 +113,12 @@ 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 
+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 
+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::
@@ -131,7 +131,7 @@ calculations.
 
 Additional Resources:
 
-* `spatialreference.org`__: A Django-powered database of spatial reference 
+* `spatialreference.org`__: A Django-powered database of spatial reference
   systems.
 * `The State Plane Coordinate System`__: A website covering the various
   projection systems used in the United States.  Much of the U.S. spatial
@@ -150,7 +150,7 @@ __ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinate
 .. attribute:: GeometryField.spatial_index
 
 Defaults to ``True``.  Creates a spatial index for the given geometry
-field. 
+field.
 
 .. note::
 
@@ -185,7 +185,7 @@ three-dimensonal support.
 .. attribute:: GeometryField.geography
 
 If set to ``True``, this option will create a database column of
-type geography, rather than geometry.  Please refer to the 
+type geography, rather than geometry.  Please refer to the
 :ref:`geography type <geography-type>` section below for more
 details.
 
@@ -212,7 +212,7 @@ 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 
+only the following additional :ref:`spatial lookups <spatial-lookups>` are
 available for geography columns:
 
 * :lookup:`bboverlaps`
@@ -231,13 +231,13 @@ determining `when to use geography data type over geometry data type
 .. currentmodule:: django.contrib.gis.db.models
 .. class:: GeoManager
 
-In order to conduct geographic queries, each geographic model requires 
+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 
+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 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
@@ -251,7 +251,7 @@ model::
         zipcode = models.ForeignKey(Zipcode)
         objects = models.GeoManager()
 
-The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, 
+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)')
@@ -260,7 +260,7 @@ for example::
 .. [#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. 
+.. [#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.

docs/ref/contrib/gis/testing.txt

@@ -6,7 +6,7 @@ Testing GeoDjango Apps
 
 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 :ref:`topics-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.

docs/ref/contrib/gis/tutorial.txt

@@ -15,8 +15,8 @@ geographic web applications, like location-based services.  Some features includ
   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 :ref:`regular tutorial <intro-tutorial01>` to introduce
+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::
@@ -27,12 +27,12 @@ yourself with basic Django concepts.
 
 This tutorial is going to guide you through guide the user 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 
+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 
+    Proceed through the tutorial sections sequentially for step-by-step
     instructions.
 
 .. _OGC: http://www.opengeospatial.org/
@@ -51,11 +51,11 @@ Create a Spatial Database
     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 
+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
@@ -65,9 +65,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>`
         $ 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 
+    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
@@ -92,7 +92,7 @@ Configure ``settings.py``
 The ``geodjango`` project settings are stored in the ``settings.py`` file.  Edit
 the database connection settings appropriately::
 
-    DATABASES = { 
+    DATABASES = {
         'default': {
              'ENGINE': 'django.contrib.gis.db.backends.postgis',
              'NAME': 'geodjango',
@@ -104,7 +104,7 @@ the database connection settings appropriately::
 
     These database settings are for Django 1.2 and above.
 
-In addition, modify the :setting:`INSTALLED_APPS` setting to include 
+In addition, modify the :setting:`INSTALLED_APPS` setting to include
 :mod:`django.contrib.admin`, :mod:`django.contrib.gis`,
 and ``world`` (our newly created application)::
 
@@ -142,8 +142,8 @@ 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). 
+* ``.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.
 
@@ -153,7 +153,7 @@ __ http://en.wikipedia.org/wiki/Shapefile
 Use ``ogrinfo`` to examine spatial data
 ---------------------------------------
 
-The GDAL ``ogrinfo`` utility is excellent for examining metadata about 
+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
@@ -192,13 +192,13 @@ and use the ``-so`` option to get only important summary information::
     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"), 
+(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`_ website, this shows
-you how to determine this information yourself when such metadata is not 
+you how to determine this information yourself when such metadata is not
 provided.
 
 Geographic Models
@@ -213,7 +213,7 @@ 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 
+        # Regular Django fields corresponding to the attributes in the
 	# world borders shapefile.
         name = models.CharField(max_length=50)
         area = models.IntegerField()
@@ -227,7 +227,7 @@ create a GeoDjango model to represent this data::
     	lon = models.FloatField()
     	lat = models.FloatField()
 
-	# GeoDjango-specific: a geometry field (MultiPolygonField), and 
+	# GeoDjango-specific: a geometry field (MultiPolygonField), and
         # overriding the default manager with a GeoManager instance.
 	mpoly = models.MultiPolygonField()
 	objects = models.GeoManager()
@@ -235,23 +235,23 @@ create a GeoDjango model to represent this data::
         # So the model is pluralized correctly in the admin.
         class Meta:
             verbose_name_plural = "World Borders"
- 
-        # Returns the string representation of the model.       
+
+        # 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 
+2. The model overrides its default manager with
    :class:`~django.contrib.gis.db.models.GeoManager`; this is *required*
-   to perform spatial queries.  
+   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. 
+with an integer corresponding to the coordinate system of your choice.
 
 __ http://en.wikipedia.org/wiki/SRID
 
@@ -259,7 +259,7 @@ 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`` 
+First, let's look at the SQL that will generate the table for the ``WorldBorders``
 model::
 
     $ python manage.py sqlall world
@@ -295,7 +295,7 @@ If satisfied, you may then create this table in the database by running the
     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 
+do so (not required now, may be done at any point in the future using the
 ``createsuperuser`` management command).
 
 Importing Spatial Data
@@ -303,11 +303,11 @@ 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 
+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 
+* `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
@@ -339,7 +339,7 @@ tutorial, then we can determine the path using Python's built-in
     >>> 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 
+Now, the world borders shapefile may be opened using GeoDjango's
 :class:`~django.contrib.gis.gdal.DataSource` interface::
 
     >>> from django.contrib.gis.gdal import *
@@ -347,7 +347,7 @@ Now, the world borders shapefile may be opened using GeoDjango's
     >>> print ds
     / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile)
 
-Data source objects can have different layers of geospatial features; however, 
+Data source objects can have different layers of geospatial features; however,
 shapefiles are only allowed to have one layer::
 
     >>> print len(ds)
@@ -367,10 +367,10 @@ contains::
 .. note::
 
     Unfortunately the shapefile data format does not allow for greater
-    specificity with regards to geometry types.  This shapefile, like 
+    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`` 
+    as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon``
     type geometry -- thus a ``MultiPolygonField`` is used in our model's
     definition instead.
 
@@ -391,7 +391,7 @@ system associated with it -- if it does, the ``srs`` attribute will return a
 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 
+In addition, shapefiles also support attribute fields that may contain
 additional data.  Here are the fields on the World Borders layer:
 
     >>> print lyr.fields
@@ -403,8 +403,8 @@ 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 
+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)::
 
@@ -427,7 +427,7 @@ And individual features may be retrieved by their feature ID::
     >>> print feat.get('NAME')
     San Marino
 
-Here the boundary geometry for San Marino is extracted and looking 
+Here the boundary geometry for San Marino is extracted and looking
 exported to WKT and GeoJSON::
 
     >>> geom = feat.geom
@@ -465,7 +465,7 @@ We're going to dive right in -- create a file called ``load.py`` inside the
     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, 
+        lm = LayerMapping(WorldBorders, world_shp, world_mapping,
                           transform=False, encoding='iso-8859-1')
 
         lm.save(strict=True, verbose=verbose)
@@ -473,8 +473,8 @@ We're going to dive right in -- create a file called ``load.py`` inside the
 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. 
+  ``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
@@ -503,10 +503,10 @@ do the work::
 
 Try ``ogrinspect``
 ------------------
-Now that you've seen how to define geographic models and import data with the 
+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 
+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::
@@ -525,13 +525,13 @@ and mapping dictionary created above, automatically::
 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 
+* 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 
+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.
@@ -584,7 +584,7 @@ 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 
+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::
@@ -611,7 +611,7 @@ available -- the :ref:`ref-gis-db-api` documentation has more.
 
 Automatic Spatial Transformations
 ---------------------------------
-When querying the spatial database GeoDjango automatically transforms 
+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
@@ -634,26 +634,26 @@ of abstraction::
     ('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" 
+    "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>]   
+    [<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 
+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 
+    >>> 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>
@@ -682,16 +682,16 @@ Google
 Geographic Admin
 ----------------
 
-GeoDjango extends :ref:`Django's admin application <ref-contrib-admin>` to
-enable support for editing geometry fields.
+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 
+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 
+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

docs/ref/contrib/humanize.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-humanize:
-
 ========================
 django.contrib.humanize
 ========================

docs/ref/contrib/index.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-index:
-
 ====================
 ``contrib`` packages
 ====================
@@ -46,8 +44,8 @@ admin
 =====
 
 The automatic Django administrative interface. For more information, see
-:ref:`Tutorial 2 <intro-tutorial02>` and the
-:ref:`admin documentation <ref-contrib-admin>`.
+:doc:`Tutorial 2 </intro/tutorial02>` and the
+:doc:`admin documentation </ref/contrib/admin/index>`.
 
 Requires the auth_ and contenttypes_ contrib packages to be installed.
 
@@ -56,16 +54,16 @@ auth
 
 Django's authentication framework.
 
-See :ref:`topics-auth`.
+See :doc:`/topics/auth`.
 
 comments
 ========
 
 .. versionchanged:: 1.0
-   The comments application has been rewriten. See :ref:`ref-contrib-comments-upgrade`
+   The comments application has been rewriten. See :doc:`/ref/contrib/comments/upgrade`
    for information on howto upgrade.
 
-A simple yet flexible comments system. See :ref:`ref-contrib-comments-index`.
+A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`.
 
 contenttypes
 ============
@@ -73,21 +71,21 @@ contenttypes
 A light framework for hooking into "types" of content, where each installed
 Django model is a separate content type.
 
-See the :ref:`contenttypes documentation <ref-contrib-contenttypes>`.
+See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`.
 
 csrf
 ====
 
 A middleware for preventing Cross Site Request Forgeries
 
-See the :ref:`csrf documentation <ref-contrib-csrf>`.
+See the :doc:`csrf documentation </ref/contrib/csrf>`.
 
 flatpages
 =========
 
 A framework for managing simple "flat" HTML content in a database.
 
-See the :ref:`flatpages documentation <ref-contrib-flatpages>`.
+See the :doc:`flatpages documentation </ref/contrib/flatpages>`.
 
 Requires the sites_ contrib package to be installed as well.
 
@@ -103,14 +101,14 @@ An abstraction of the following workflow:
 
 "Display an HTML form, force a preview, then do something with the submission."
 
-See the :ref:`form preview documentation <ref-contrib-formtools-form-preview>`.
+See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`.
 
 django.contrib.formtools.wizard
 --------------------------------
 
 Splits forms across multiple Web pages.
 
-See the :ref:`form wizard documentation <ref-contrib-formtools-form-wizard>`.
+See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`.
 
 gis
 ====
@@ -118,14 +116,14 @@ gis
 A world-class geospatial framework built on top of Django, that enables
 storage, manipulation and display of spatial data.
 
-See the :ref:`ref-contrib-gis` documentation for more.
+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 :ref:`humanize documentation <ref-contrib-humanize>`.
+See the :doc:`humanize documentation </ref/contrib/humanize>`.
 
 localflavor
 ===========
@@ -134,7 +132,7 @@ 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 :ref:`localflavor documentation <ref-contrib-localflavor>`.
+See the :doc:`localflavor documentation </ref/contrib/localflavor>`.
 
 .. _ref-contrib-markup:
 
@@ -183,21 +181,21 @@ messages
 A framework for storing and retrieving temporary cookie- or session-based
 messages
 
-See the :ref:`messages documentation <ref-contrib-messages>`.
+See the :doc:`messages documentation </ref/contrib/messages>`.
 
 redirects
 =========
 
 A framework for managing redirects.
 
-See the :ref:`redirects documentation <ref-contrib-redirects>`.
+See the :doc:`redirects documentation </ref/contrib/redirects>`.
 
 sessions
 ========
 
 A framework for storing data in anonymous sessions.
 
-See the :ref:`sessions documentation <topics-http-sessions>`.
+See the :doc:`sessions documentation </topics/http/sessions>`.
 
 sites
 =====
@@ -206,21 +204,21 @@ 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 :ref:`sites documentation <ref-contrib-sites>`.
+See the :doc:`sites documentation </ref/contrib/sites>`.
 
 sitemaps
 ========
 
 A framework for generating Google sitemap XML files.
 
-See the :ref:`sitemaps documentation <ref-contrib-sitemaps>`.
+See the :doc:`sitemaps documentation </ref/contrib/sitemaps>`.
 
 syndication
 ===========
 
 A framework for generating syndication feeds, in RSS and Atom, quite easily.
 
-See the :ref:`syndication documentation <ref-contrib-syndication>`.
+See the :doc:`syndication documentation </ref/contrib/syndication>`.
 
 webdesign
 =========
@@ -228,7 +226,7 @@ webdesign
 Helpers and utilities targeted primarily at Web *designers* rather than
 Web *developers*.
 
-See the :ref:`Web design helpers documentation <ref-contrib-webdesign>`.
+See the :doc:`Web design helpers documentation </ref/contrib/webdesign>`.
 
 Other add-ons
 =============

docs/ref/contrib/localflavor.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-localflavor:
-
 ==========================
 The "local flavor" add-ons
 ==========================
@@ -17,7 +15,7 @@ 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 :ref:`forms <topics-forms-index>` framework -- for example, a
+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
@@ -74,7 +72,7 @@ Countries currently supported by :mod:`~django.contrib.localflavor` are:
 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 :ref:`forms <topics-forms-index>`, but with non-US default formats.
+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

docs/ref/contrib/messages.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-messages:
-
 ======================
 The messages framework
 ======================
@@ -20,8 +18,8 @@ with a specific ``level`` that determines its priority (e.g., ``info``,
 Enabling messages
 =================
 
-Messages are implemented through a :ref:`middleware <ref-middleware>`
-class and corresponding :ref:`context processor <ref-templates-api>`.
+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:
 
@@ -29,7 +27,7 @@ To enable message functionality, do the following:
       it contains ``'django.contrib.messages.middleware.MessageMiddleware'``.
 
       If you are using a :ref:`storage backend <message-storage-backends>` that
-      relies on :ref:`sessions <topics-http-sessions>` (the default),
+      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`.
@@ -106,7 +104,7 @@ 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 :ref:`release process documentation <internals-release-process>`.
+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``
@@ -300,7 +298,7 @@ example::
     messages.info(request, 'Hello world.', fail_silently=True)
 
 Internally, Django uses this functionality in the create, update, and delete
-:ref:`generic views <topics-generic-views>` so that they work even if the
+:doc:`generic views </topics/http/generic-views>` so that they work even if the
 message framework is disabled.
 
 .. note::
@@ -343,7 +341,7 @@ window/tab will have its own browsing context.
 Settings
 ========
 
-A few :ref:`Django settings <ref-settings>` give you control over message
+A few :doc:`Django settings </ref/settings>` give you control over message
 behavior:
 
 MESSAGE_LEVEL

docs/ref/contrib/redirects.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-redirects:
-
 =================
 The redirects app
 =================
@@ -47,8 +45,8 @@ 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 :ref:`middleware docs
-<topics-http-middleware>`.
+For more on middleware, read the :doc:`middleware docs
+</topics/http/middleware>`.
 
 How to add, change and delete redirects
 =======================================
@@ -65,8 +63,8 @@ Via the Python API
 
 .. class:: models.Redirect
 
-    Redirects are represented by a standard :ref:`Django model <topics-db-models>`,
+    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 :ref:`Django database API <topics-db-queries>`.
+    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

docs/ref/contrib/sitemaps.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-sitemaps:
-
 =====================
 The sitemap framework
 =====================
@@ -23,10 +21,10 @@ 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 :ref:`syndication framework
-<ref-contrib-syndication>`. To create a sitemap, just write a
+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
-:ref:`URLconf <topics-http-urls>`.
+:doc:`URLconf </topics/http/urls>`.
 
 Installation
 ============
@@ -52,7 +50,7 @@ Initialization
 ==============
 
 To activate sitemap generation on your Django site, add this line to your
-:ref:`URLconf <topics-http-urls>`::
+:doc:`URLconf </topics/http/urls>`::
 
    (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
 
@@ -227,7 +225,7 @@ The sitemap framework provides a couple convenience classes for common cases:
 .. class:: GenericSitemap
 
     The :class:`django.contrib.sitemaps.GenericSitemap` class works with any
-    :ref:`generic views <ref-generic-views>` you already have.
+    :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
@@ -240,7 +238,7 @@ The sitemap framework provides a couple convenience classes for common cases:
 Example
 -------
 
-Here's an example of a :ref:`URLconf <topics-http-urls>` using both::
+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

docs/ref/contrib/sites.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-sites:
-
 =====================
 The "sites" framework
 =====================
@@ -260,7 +258,7 @@ The ``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 :ref:`manager <topics-db-managers>` that
+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`.
 
@@ -322,7 +320,7 @@ 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 :ref:`manager documentation <topics-db-managers>`, if
+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 --
@@ -387,7 +385,7 @@ Here's how Django uses the sites framework:
 
 .. versionadded:: 1.0
 
-Some :ref:`django.contrib <ref-contrib-index>` applications take advantage of
+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

docs/ref/contrib/syndication.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-syndication:
-
 ==============================
 The syndication feed framework
 ==============================
@@ -38,8 +36,8 @@ 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 :ref:`URLconf
-<topics-http-urls>`.
+and point to an instance of it in your :doc:`URLconf
+</topics/http/urls>`.
 
 Feed classes
 ------------
@@ -54,7 +52,7 @@ 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 :ref:`URLconf <topics-http-urls>`.
+are views which can be used in your :doc:`URLconf </topics/http/urls>`.
 
 A simple example
 ----------------
@@ -80,7 +78,7 @@ latest five news items::
             return item.description
 
 To connect a URL to this feed, put an instance of the Feed object in
-your :ref:`URLconf <topics-http-urls>`. For example::
+your :doc:`URLconf </topics/http/urls>`. For example::
 
     from django.conf.urls.defaults import *
     from myproject.feeds import LatestEntriesFeed
@@ -102,7 +100,7 @@ Note:
 * :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
-  :ref:`object-relational mapper <ref-models-querysets>`, :meth:`items()`
+  :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.
@@ -123,7 +121,7 @@ into those elements.
       both.
 
       If you want to do any special formatting for either the title or
-      description, :ref:`Django templates <topics-templates>` can be used
+      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
@@ -167,7 +165,7 @@ 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 :ref:`URLconf <topics-http-urls>` so feeds can output
+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:
@@ -175,7 +173,7 @@ 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 :ref:`URLconf <topics-http-urls>` line such as::
+These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
 
     (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()),
 

docs/ref/contrib/webdesign.txt

@@ -1,5 +1,3 @@
-.. _ref-contrib-webdesign:
-
 ========================
 django.contrib.webdesign
 ========================
@@ -9,13 +7,13 @@ django.contrib.webdesign
               rather than Web *developers*.
 
 The ``django.contrib.webdesign`` package, part of the
-:ref:`"django.contrib" add-ons <ref-contrib-index>`, provides various Django
+: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
-:ref:`suggest them <internals-contributing>`.
+:doc:`suggest them </internals/contributing>`.
 
 Template tags
 =============

docs/ref/databases.txt

@@ -1,5 +1,3 @@
-.. _ref-databases:
-
 =========
 Databases
 =========
@@ -50,7 +48,7 @@ aggregate with a database backend that falls within the affected release range.
 Transaction handling
 ---------------------
 
-:ref:`By default <topics-db-transactions>`, Django starts a transaction when a
+: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.
@@ -266,7 +264,7 @@ table (usually called ``django_session``) and the
 Connecting to the database
 --------------------------
 
-Refer to the :ref:`settings documentation <ref-settings>`.
+Refer to the :doc:`settings documentation </ref/settings>`.
 
 Connection settings are used in this order:
 

docs/ref/django-admin.txt

@@ -1,5 +1,3 @@
-.. _ref-django-admin:
-
 =============================
 django-admin.py and manage.py
 =============================
@@ -104,7 +102,7 @@ compilemessages
    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 :ref:`topics-i18n`.
+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.
@@ -119,7 +117,7 @@ createcachetable
 .. django-admin:: createcachetable
 
 Creates a cache table named ``tablename`` for use with the database cache
-backend. See :ref:`topics-cache` for more information.
+backend. See :doc:`/topics/cache` for more information.
 
 .. versionadded:: 1.2
 
@@ -151,8 +149,8 @@ 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.
 
-This command is only available if Django's :ref:`authentication system
-<topics-auth>` (``django.contrib.auth``) is installed.
+This command is only available if Django's :doc:`authentication system
+</topics/auth>` (``django.contrib.auth``) is installed.
 
 dbshell
 -------
@@ -529,8 +527,8 @@ 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 :ref:`FastCGI deployment documentation
-<howto-deployment-fastcgi>` for details. Requires the Python FastCGI module from
+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/
@@ -616,7 +614,7 @@ 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 :ref:`howto-static-files`.
+you want to configure Django to serve static media, read :doc:`/howto/static-files`.
 
 shell
 -----
@@ -822,7 +820,7 @@ test <app or test identifier>
 
 .. django-admin:: test
 
-Runs tests for all installed models. See :ref:`topics-testing` for more
+Runs tests for all installed models. See :doc:`/topics/testing` for more
 information.
 
 .. versionadded:: 1.2
@@ -847,7 +845,7 @@ For example, this command::
 
 ...would perform the following steps:
 
-    1. Create a test database, as described in :ref:`topics-testing`.
+    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
@@ -855,7 +853,7 @@ For example, this command::
 
 This is useful in a number of ways:
 
-    * When you're writing :ref:`unit tests <topics-testing>` of how your views
+    * 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.
 
@@ -1116,4 +1114,4 @@ distribution. It enables tab-completion of ``django-admin.py`` and
       with ``sql``.
 
 
-See :ref:`howto-custom-management-commands` for how to add customized actions.
+See :doc:`/howto/custom-management-commands` for how to add customized actions.

docs/ref/exceptions.txt

@@ -1,5 +1,3 @@
-.. _ref-exceptions:
-
 =================
 Django Exceptions
 =================

docs/ref/files/file.txt

@@ -1,5 +1,3 @@
-.. _ref-files-file:
-
 The ``File`` object
 ===================
 
@@ -20,14 +18,14 @@ Django's ``File`` has the following attributes and methods:
 
     The absolute path to the file's location on a local filesystem.
 
-    :ref:`Custom file storage systems <howto-custom-file-storage>` may not store
+    :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
     files locally; files stored on these systems will have a ``path`` of
     ``None``.
 
 .. attribute:: File.url
 
     The URL where the file can be retrieved. This is often useful in
-    :ref:`templates <topics-templates>`; for example, a bit of a template for
+    :doc:`templates </topics/templates>`; for example, a bit of a template for
     displaying a ``Car`` (see above) might look like:
     
     .. code-block:: html+django

docs/ref/files/index.txt

@@ -1,5 +1,3 @@
-.. _ref-files-index:
-
 =============
 File handling
 =============

docs/ref/files/storage.txt

@@ -1,5 +1,3 @@
-.. _ref-files-storage:
-
 File storage API
 ================
 

docs/ref/forms/api.txt

@@ -1,5 +1,3 @@
-.. _ref-forms-api:
-
 =============
 The Forms API
 =============
@@ -11,7 +9,7 @@ The Forms API
 .. admonition:: About this document
 
     This document covers the gritty details of Django's forms API. You should
-    read the :ref:`introduction to working with forms <topics-forms-index>`
+    read the :doc:`introduction to working with forms </topics/forms/index>`
     first.
 
 .. _ref-forms-api-bound-unbound:
@@ -262,7 +260,7 @@ 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 :ref:`ref-forms-validation`.
+fields). More information about this is in :doc:`/ref/forms/validation`.
 
 Outputting forms as HTML
 ------------------------

docs/ref/forms/fields.txt

@@ -1,5 +1,3 @@
-.. _ref-forms-fields:
-
 ===========
 Form fields
 ===========
@@ -192,7 +190,7 @@ The callable will be evaluated only when the unbound form is displayed, not when
 .. attribute:: Field.widget
 
 The ``widget`` argument lets you specify a ``Widget`` class to use when
-rendering this ``Field``. See :ref:`ref-forms-widgets` for more information.
+rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information.
 
 ``help_text``
 ~~~~~~~~~~~~~
@@ -267,7 +265,7 @@ error message keys it uses.
 The ``validators`` argument lets you provide a list of validation functions
 for this field.
 
-See the :ref:`validators documentation <ref-validators>` for more information.
+See the :doc:`validators documentation </ref/validators>` for more information.
 
 ``localize``
 ~~~~~~~~~~~~
@@ -516,8 +514,8 @@ given length.
     * 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 :ref:`file uploads
-documentation <topics-http-file-uploads>`.
+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>`.