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/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
+
+        ========
+        Settings
+        ========
+
+        ...
+
+        .. _available-settings:
 
         Available settings
         ==================
 
         ...
 
-    * Next, if you look at the ``topics/settings.txt`` document, you can see how
-      a link to ``ref/settings`` works::
+        .. _deprecated-settings:
 
-        Available settings
-        ==================
+        Deprecated settings
+        ===================
 
-        For a full list of available settings, see the :ref:`settings reference
-        <ref-settings>`.
+        ...
 
-    * Next, notice how the settings (right now just the top few) are annotated::
+    * 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:
+
+      .. 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.