Fixed #15233 -- reST/Sphinx markup corrections in numerous areas, mostly…

Fixed #15233 -- reST/Sphinx markup corrections in numerous areas, mostly centering around bad crossref targets. Thanks to Aryeh Leib Taurog for the draft patch.

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

docs/ref/contrib/admin/index.txt

@@ -1110,6 +1110,8 @@ information.
 ============================
 
 .. class:: InlineModelAdmin
+.. class:: TabularInline
+.. class:: StackedInline
 
     The admin interface has the ability to edit models on the same page as a
     parent model. These are called inlines. Suppose you have these two models::
@@ -1134,8 +1136,8 @@ information.
 
     Django provides two subclasses of ``InlineModelAdmin`` and they are:
 
-        * ``TabularInline``
-        * ``StackedInline``
+        * :class:`~django.contrib.admin.TabularInline`
+        * :class:`~django.contrib.admin.StackedInline`
 
     The difference between these two is merely the template used to render
     them.

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

@@ -2,7 +2,7 @@
 Form preview
 ============
 
-.. module:: django.contrib.formtools
+.. module:: django.contrib.formtools.preview
     :synopsis: Displays an HTML form, forces a preview, then does something
                with the submission.
 
@@ -26,7 +26,7 @@ application takes care of the following workflow:
       b. If it's not valid, redisplays the form with error messages.
    3. When the "confirmation" form is submitted from the preview page, calls
       a hook that you define -- a
-      :meth:`~django.contrib.formtools.FormPreview.done()` method that gets
+      :meth:`~django.contrib.formtools.preview.FormPreview.done()` method that gets
       passed the valid data.
 
 The framework enforces the required preview by passing a shared-secret hash to
@@ -50,8 +50,8 @@ How to use ``FormPreview``
               :file:`django/contrib/formtools/templates` directory, and add that
               directory to your :setting:`TEMPLATE_DIRS` setting.
 
-    2. Create a :class:`~django.contrib.formtools.FormPreview` subclass that
-       overrides the :meth:`~django.contrib.formtools.FormPreview.done()`
+    2. Create a :class:`~django.contrib.formtools.preview.FormPreview` subclass that
+       overrides the :meth:`~django.contrib.formtools.preview.FormPreview.done()`
        method::
 
            from django.contrib.formtools.preview import FormPreview
@@ -70,7 +70,7 @@ How to use ``FormPreview``
        is the end result of the form being submitted.
 
     3. Change your URLconf to point to an instance of your
-       :class:`~django.contrib.formtools.FormPreview` subclass::
+       :class:`~django.contrib.formtools.preview.FormPreview` subclass::
 
            from myapp.preview import SomeModelFormPreview
            from myapp.forms import SomeModelForm
@@ -89,11 +89,11 @@ How to use ``FormPreview``
 
 .. class:: FormPreview
 
-A :class:`~django.contrib.formtools.FormPreview` class is a simple Python class
+A :class:`~django.contrib.formtools.preview.FormPreview` class is a simple Python class
 that represents the preview workflow.
-:class:`~django.contrib.formtools.FormPreview` classes must subclass
+:class:`~django.contrib.formtools.preview.FormPreview` classes must subclass
 ``django.contrib.formtools.preview.FormPreview`` and override the
-:meth:`~django.contrib.formtools.FormPreview.done()` method. They can live
+:meth:`~django.contrib.formtools.preview.FormPreview.done()` method. They can live
 anywhere in your codebase.
 
 ``FormPreview`` templates
@@ -102,8 +102,8 @@ anywhere in your codebase.
 By default, the form is rendered via the template :file:`formtools/form.html`,
 and the preview page is rendered via the template :file:`formtools/preview.html`.
 These values can be overridden for a particular form preview by setting
-:attr:`~django.contrib.formtools.FormPreview.preview_template` and
-:attr:`~django.contrib.formtools.FormPreview.form_template` attributes on the
+:attr:`~django.contrib.formtools.preview.FormPreview.preview_template` and
+:attr:`~django.contrib.formtools.preview.FormPreview.form_template` attributes on the
 FormPreview subclass. See :file:`django/contrib/formtools/templates` for the
 default templates.
 

docs/ref/forms/widgets.txt

@@ -160,6 +160,8 @@ commonly used groups of widgets:
     Takes two optional arguments, ``date_format`` and ``time_format``, which
     work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
 
+.. currentmodule:: django.forms.extras.widgets
+
 .. class:: SelectDateWidget
 
     Wrapper around three select widgets: one each for month, day, and year.
@@ -180,6 +182,7 @@ commonly used groups of widgets:
 
 Specifying widgets
 ------------------
+.. currentmodule:: django.forms
 
 .. attribute:: Form.widget
 

docs/ref/models/querysets.txt

@@ -1749,6 +1749,8 @@ SQL equivalents::
 Aggregation functions
 ---------------------
 
+.. currentmodule:: django.db.models
+
 Django provides the following aggregation functions in the
 ``django.db.models`` module. For details on how to use these
 aggregate functions, see
@@ -1759,100 +1761,100 @@ Avg
 
 .. class:: Avg(field)
 
-Returns the mean value of the given field.
+    Returns the mean value of the given field.
 
-    * Default alias: ``<field>__avg``
-    * Return type: float
+        * Default alias: ``<field>__avg``
+        * Return type: float
 
 Count
 ~~~~~
 
 .. class:: Count(field, distinct=False)
 
-Returns the number of objects that are related through the provided field.
+    Returns the number of objects that are related through the provided field.
 
-    * Default alias: ``<field>__count``
-    * Return type: integer
+        * Default alias: ``<field>__count``
+        * Return type: integer
 
-Has one optional argument:
+    Has one optional argument:
 
-.. attribute:: distinct
+    .. attribute:: distinct
 
-    If distinct=True, the count will only include unique instances. This has
-    the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
+        If distinct=True, the count will only include unique instances. This has
+        the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
 
 Max
 ~~~
 
 .. class:: Max(field)
 
-Returns the maximum value of the given field.
+    Returns the maximum value of the given field.
 
-    * Default alias: ``<field>__max``
-    * Return type: same as input field
+        * Default alias: ``<field>__max``
+        * Return type: same as input field
 
 Min
 ~~~
 
 .. class:: Min(field)
 
-Returns the minimum value of the given field.
+    Returns the minimum value of the given field.
 
-    * Default alias: ``<field>__min``
-    * Return type: same as input field
+        * Default alias: ``<field>__min``
+        * Return type: same as input field
 
 StdDev
 ~~~~~~
 
 .. class:: StdDev(field, sample=False)
 
-Returns the standard deviation of the data in the provided field.
+    Returns the standard deviation of the data in the provided field.
 
-    * Default alias: ``<field>__stddev``
-    * Return type: float
+        * Default alias: ``<field>__stddev``
+        * Return type: float
 
-Has one optional argument:
+    Has one optional argument:
 
-.. attribute:: sample
+    .. attribute:: sample
 
-    By default, ``StdDev`` returns the population standard deviation. However,
-    if ``sample=True``, the return value will be the sample standard deviation.
+        By default, ``StdDev`` returns the population standard deviation. However,
+        if ``sample=True``, the return value will be the sample standard deviation.
 
-.. admonition:: SQLite
+    .. admonition:: SQLite
 
-    SQLite doesn't provide ``StdDev`` out of the box. An implementation is
-    available as an extension module for SQLite. Consult the SQlite
-    documentation for instructions on obtaining and installing this extension.
+        SQLite doesn't provide ``StdDev`` out of the box. An implementation is
+        available as an extension module for SQLite. Consult the SQlite
+        documentation for instructions on obtaining and installing this extension.
 
 Sum
 ~~~
 
 .. class:: Sum(field)
 
-Computes the sum of all values of the given field.
+    Computes the sum of all values of the given field.
 
-    * Default alias: ``<field>__sum``
-    * Return type: same as input field
+        * Default alias: ``<field>__sum``
+        * Return type: same as input field
 
 Variance
 ~~~~~~~~
 
 .. class:: Variance(field, sample=False)
 
-Returns the variance of the data in the provided field.
+    Returns the variance of the data in the provided field.
 
-    * Default alias: ``<field>__variance``
-    * Return type: float
+        * Default alias: ``<field>__variance``
+        * Return type: float
 
-Has one optional argument:
+    Has one optional argument:
 
-.. attribute:: sample
+    .. attribute:: sample
 
-    By default, ``Variance`` returns the population variance. However,
-    if ``sample=True``, the return value will be the sample variance.
+        By default, ``Variance`` returns the population variance. However,
+        if ``sample=True``, the return value will be the sample variance.
 
-.. admonition:: SQLite
+    .. admonition:: SQLite
 
-    SQLite doesn't provide ``Variance`` out of the box. An implementation is
-    available as an extension module for SQLite. Consult the SQlite
-    documentation for instructions on obtaining and installing this extension.
+        SQLite doesn't provide ``Variance`` out of the box. An implementation is
+        available as an extension module for SQLite. Consult the SQlite
+        documentation for instructions on obtaining and installing this extension.

docs/topics/auth.txt

@@ -615,6 +615,8 @@ Django provides two functions in :mod:`django.contrib.auth`:
 Manually checking a user's password
 -----------------------------------
 
+.. currentmodule:: django.contrib.auth.models
+
 .. function:: check_password()
 
     If you'd like to manually authenticate a user by comparing a plain-text
@@ -627,6 +629,8 @@ Manually checking a user's password
 How to log a user out
 ---------------------
 
+.. currentmodule:: django.contrib.auth
+
 .. function:: logout()
 
     To log out a user who has been logged in via
@@ -871,11 +875,13 @@ The login_required decorator
 Other built-in views
 --------------------
 
+.. module:: django.contrib.auth.views
+
 In addition to the :func:`~views.login` view, the authentication system
 includes a few other useful built-in views located in
 :mod:`django.contrib.auth.views`:
 
-.. function:: views.logout(request, [next_page, template_name, redirect_field_name])
+.. function:: logout(request, [next_page, template_name, redirect_field_name])
 
     Logs a user out.
 
@@ -895,7 +901,7 @@ includes a few other useful built-in views located in
 
         * ``title``: The string "Logged out", localized.
 
-.. function:: views.logout_then_login(request[, login_url])
+.. function:: logout_then_login(request[, login_url])
 
     Logs a user out, then redirects to the login page.
 
@@ -904,7 +910,7 @@ includes a few other useful built-in views located in
         * ``login_url``: The URL of the login page to redirect to. This will
           default to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.
 
-.. function:: views.password_change(request[, template_name, post_change_redirect, password_change_form])
+.. function:: password_change(request[, template_name, post_change_redirect, password_change_form])
 
     Allows a user to change their password.
 
@@ -928,7 +934,7 @@ includes a few other useful built-in views located in
 
         * ``form``: The password change form.
 
-.. function:: views.password_change_done(request[, template_name])
+.. function:: password_change_done(request[, template_name])
 
     The page shown after a user has changed their password.
 
@@ -938,11 +944,14 @@ includes a few other useful built-in views located in
           default to :file:`registration/password_change_done.html` if not
           supplied.
 
-.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email])
+.. function:: password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email])
 
     Allows a user to reset their password by generating a one-time use link
     that can be used to reset the password, and sending that link to the
     user's registered e-mail address.
+    
+    .. versionchanged:: 1.3
+        The ``from_email`` argument was added.
 
     **Optional arguments:**
 
@@ -964,8 +973,6 @@ includes a few other useful built-in views located in
         * ``post_reset_redirect``: The URL to redirect to after a successful
           password change.
 
-        .. versionchanged:: 1.3
-
         * ``from_email``: A valid e-mail address. By default Django uses
           the :setting:`DEFAULT_FROM_EMAIL`.
 
@@ -973,7 +980,7 @@ includes a few other useful built-in views located in
 
         * ``form``: The form for resetting the user's password.
 
-.. function:: views.password_reset_done(request[, template_name])
+.. function:: password_reset_done(request[, template_name])
 
     The page shown after a user has reset their password.
 
@@ -983,7 +990,7 @@ includes a few other useful built-in views located in
           default to :file:`registration/password_reset_done.html` if not
           supplied.
 
-.. function:: views.redirect_to_login(next[, login_url, redirect_field_name])
+.. function:: redirect_to_login(next[, login_url, redirect_field_name])
 
     Redirects to the login page, and then back to another URL after a
     successful login.
@@ -1001,6 +1008,7 @@ includes a few other useful built-in views located in
           URL to redirect to after log out. Overrides ``next`` if the given
           ``GET`` parameter is passed.
 
+
 .. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])
 
     Presents a form for entering a new password.
@@ -1073,7 +1081,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
 Limiting access to logged-in users that pass a test
 ---------------------------------------------------
 
-.. currentmodule:: django.contrib.auth
+.. currentmodule:: django.contrib.auth.decorators
 
 To limit access based on certain permissions or some other test, you'd do
 essentially the same thing as described in the previous section.
@@ -1088,7 +1096,7 @@ checks to make sure the user is logged in and has the permission
             return HttpResponse("You can't vote in this poll.")
         # ...
 
-.. function:: decorators.user_passes_test()
+.. function:: user_passes_test()
 
     As a shortcut, you can use the convenient ``user_passes_test`` decorator::
 
@@ -1126,7 +1134,7 @@ checks to make sure the user is logged in and has the permission
 The permission_required decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. function:: decorators.permission_required()
+.. function:: permission_required()
 
     It's a relatively common task to check whether a user has a particular
     permission. For that reason, Django provides a shortcut for that case: the
@@ -1155,6 +1163,8 @@ The permission_required decorator
     As in the :func:`~decorators.login_required` decorator, ``login_url``
     defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`.
 
+.. currentmodule:: django.contrib.auth
+
 Limiting access to generic views
 --------------------------------
 
@@ -1249,7 +1259,9 @@ closing tasks.)
 API reference
 -------------
 
-.. class:: models.Permission
+.. currentmodule:: django.contrib.auth.models
+
+.. class:: Permission
 
     Just like users, permissions are implemented in a Django model that lives
     in `django/contrib/auth/models.py`_.
@@ -1262,16 +1274,16 @@ Fields
 :class:`~django.contrib.auth.models.Permission` objects have the following
 fields:
 
-.. attribute:: models.Permission.name
+.. attribute:: Permission.name
 
     Required. 50 characters or fewer. Example: ``'Can vote'``.
 
-.. attribute:: models.Permission.content_type
+.. attribute:: Permission.content_type
 
     Required. A reference to the ``django_content_type`` database table, which
     contains a record for each installed Django model.
 
-.. attribute:: models.Permission.codename
+.. attribute:: Permission.codename
 
     Required. 100 characters or fewer. Example: ``'can_vote'``.
 
@@ -1281,6 +1293,8 @@ Methods
 :class:`~django.contrib.auth.models.Permission` objects have the standard
 data-access methods like any other :doc:`Django model </ref/models/instances>`.
 
+.. currentmodule:: django.contrib.auth
+
 Authentication data in templates
 ================================
 

docs/topics/http/decorators.txt

@@ -45,7 +45,7 @@ These decorators can be used to generate ``ETag`` and ``Last-Modified``
 headers; see
 :doc:`conditional view processing </topics/conditional-view-processing>`.
 
-.. currentmodule:: django.views.decorators.http
+.. currentmodule:: django.views.decorators.gzip
 
 GZip compression
 ================

docs/topics/http/file-uploads.txt

@@ -2,7 +2,7 @@
 File Uploads
 ============
 
-.. currentmodule:: django.core.files
+.. currentmodule:: django.core.files.uploadedfile
 
 When Django handles a file upload, the file data ends up placed in
 :attr:`request.FILES <django.http.HttpRequest.FILES>` (for more on the
@@ -59,33 +59,40 @@ into the form's constructor; this is how file data gets bound into a form.
 Handling uploaded files
 -----------------------
 
-The final piece of the puzzle is handling the actual file data from
-:attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this
-dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded
-file. You'll usually use one of these methods to access the uploaded content:
+.. class:: UploadedFile
+
+    The final piece of the puzzle is handling the actual file data from
+    :attr:`request.FILES <django.http.HttpRequest.FILES>`. Each entry in this
+    dictionary is an ``UploadedFile`` object -- a simple wrapper around an uploaded
+    file. You'll usually use one of these methods to access the uploaded content:
+
+    .. method:: read()
 
-    ``UploadedFile.read()``
         Read the entire uploaded data from the file. Be careful with this
         method: if the uploaded file is huge it can overwhelm your system if you
         try to read it into memory. You'll probably want to use ``chunks()``
         instead; see below.
 
-    ``UploadedFile.multiple_chunks()``
+    .. method:: multiple_chunks()
+
         Returns ``True`` if the uploaded file is big enough to require
         reading in multiple chunks. By default this will be any file
         larger than 2.5 megabytes, but that's configurable; see below.
 
-    ``UploadedFile.chunks()``
+    .. method:: chunks()
+
         A generator returning chunks of the file. If ``multiple_chunks()`` is
         ``True``, you should use this method in a loop instead of ``read()``.
 
         In practice, it's often easiest simply to use ``chunks()`` all the time;
         see the example below.
 
-    ``UploadedFile.name``
+    .. attribute:: name
+
         The name of the uploaded file (e.g. ``my_file.txt``).
 
-    ``UploadedFile.size``
+    .. attribute:: size
+
         The size, in bytes, of the uploaded file.
 
 There are a few other methods and attributes available on ``UploadedFile``
@@ -177,25 +184,26 @@ Three settings control Django's file upload behavior:
 ``UploadedFile`` objects
 ========================
 
-.. class:: UploadedFile
-
 In addition to those inherited from :class:`File`, all ``UploadedFile`` objects
 define the following methods/attributes:
 
-    ``UploadedFile.content_type``
-        The content-type header uploaded with the file (e.g. ``text/plain`` or
-        ``application/pdf``). Like any data supplied by the user, you shouldn't
-        trust that the uploaded file is actually this type. You'll still need to
-        validate that the file contains the content that the content-type header
-        claims -- "trust but verify."
+.. attribute:: UploadedFile.content_type
+
+    The content-type header uploaded with the file (e.g. ``text/plain`` or
+    ``application/pdf``). Like any data supplied by the user, you shouldn't
+    trust that the uploaded file is actually this type. You'll still need to
+    validate that the file contains the content that the content-type header
+    claims -- "trust but verify."
+
+.. attribute:: UploadedFile.charset
+
+    For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
+    by the browser. Again, "trust but verify" is the best policy here.
 
-    ``UploadedFile.charset``
-        For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
-        by the browser. Again, "trust but verify" is the best policy here.
+.. attribute:: UploadedFile.temporary_file_path()
 
-    ``UploadedFile.temporary_file_path()``
-        Only files uploaded onto disk will have this method; it returns the full
-        path to the temporary uploaded file.
+    Only files uploaded onto disk will have this method; it returns the full
+    path to the temporary uploaded file.
 
 .. note::
 

docs/topics/http/urls.txt

@@ -765,6 +765,8 @@ following would happen:
 Utility methods
 ===============
 
+.. module:: django.core.urlresolvers
+
 reverse()
 ---------