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