[1.2.X] Fixed #14141: docs now use the :doc: construct for links betw…

…een documents.

Thanks, Ramiro Morales.

Backport of [13608] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@13609 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/_ext/djangodocs.py

@@ -78,11 +78,11 @@ def run(self):
         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,13 +1,11 @@
-.. _faq-contributing:
-
 FAQ: Contributing code
 ======================
 
 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,15 +1,13 @@
-.. _faq-install:
-
 FAQ: Installation
 =================
 
 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
@@ -70,7 +68,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
@@ -92,7 +90,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