[soc2010/app-loading] merged trunkarchive/soc2010/app-loadingsoc2010/app-loading

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2010/app-loading@13818 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 45 insertions, 31 deletions

diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
index 4e07f73190..8c9b0f1cff 100644
--- a/docs/topics/auth.txt
+++ b/docs/topics/auth.txt
@@ -1,5 +1,3 @@
-.. _topics-auth:
-
 =============================
 User authentication in Django
 =============================
@@ -138,8 +136,8 @@ Methods
     :class:`~django.contrib.auth.models.User` objects have two many-to-many
     fields: models.User. ``groups`` and ``user_permissions``.
     :class:`~django.contrib.auth.models.User` objects can access their related
-    objects in the same way as any other :ref:`Django model
-    <topics-db-models>`:
+    objects in the same way as any other :doc:`Django model
+    </topics/db/models>`:
 
     .. code-block:: python
 
@@ -435,8 +433,6 @@ Anonymous users
       instead of ``False``.
     * :meth:`~django.contrib.auth.models.User.is_authenticated()` returns
       ``False`` instead of ``True``.
-    * :meth:`~django.contrib.auth.models.User.has_perm()` always returns
-      ``False``.
     * :meth:`~django.contrib.auth.models.User.set_password()`,
       :meth:`~django.contrib.auth.models.User.check_password()`,
       :meth:`~django.contrib.auth.models.User.save()`,
@@ -539,7 +535,7 @@ First, install the
 :class:`~django.contrib.sessions.middleware.SessionMiddleware` and
 :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
 middlewares by adding them to your :setting:`MIDDLEWARE_CLASSES` setting. See
-the :ref:`session documentation <topics-http-sessions>` for more information.
+the :doc:`session documentation </topics/http/sessions>` for more information.
 
 Once you have those middlewares installed, you'll be able to access
 :attr:`request.user <django.http.HttpRequest.user>` in views.
@@ -556,7 +552,7 @@ section). You can tell them apart with
     else:
         # Do something for anonymous users.
 
-.. _howtologauserin:
+.. _how-to-log-a-user-in:
 
 How to log a user in
 --------------------
@@ -717,6 +713,17 @@ The login_required decorator
         def my_view(request):
             ...
 
+    .. versionadded:: 1.3
+
+    :func:`~django.contrib.auth.decorators.login_required` also takes an
+    optional ``login_url`` parameter. Example::
+
+        from django.contrib.auth.decorators import login_required
+
+        @login_required(login_url='/accounts/login/')
+        def my_view(request):
+            ...
+
     :func:`~django.contrib.auth.decorators.login_required` does the following:
 
         * If the user isn't logged in, redirect to
@@ -730,9 +737,9 @@ The login_required decorator
         * If the user is logged in, execute the view normally. The view code is
           free to assume the user is logged in.
 
-Note that you'll need to map the appropriate Django view to
-:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
-the following line to your URLconf::
+Note that if you don't specify the ``login_url`` parameter, you'll need to map
+the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
+example, using the defaults, add the following line to your URLconf::
 
     (r'^accounts/login/$', 'django.contrib.auth.views.login'),
 
@@ -755,7 +762,7 @@ the following line to your URLconf::
     template context variables:
 
         * ``form``: A :class:`~django.forms.Form` object representing the login
-          form. See the :ref:`forms documentation <topics-forms-index>` for
+          form. See the :doc:`forms documentation </topics/forms/index>` for
           more on ``Form`` objects.
 
         * ``next``: The URL to redirect to after successful login. This may
@@ -771,7 +778,7 @@ the following line to your URLconf::
         * ``site_name``: An alias for ``site.name``. If you don't have the site
           framework installed, this will be set to the value of
           :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.
-          For more on sites, see :ref:`ref-contrib-sites`.
+          For more on sites, see :doc:`/ref/contrib/sites`.
 
     If you'd prefer not to call the template :file:`registration/login.html`,
     you can pass the ``template_name`` parameter via the extra arguments to
@@ -798,7 +805,8 @@ the following line to your URLconf::
         <p>Your username and password didn't match. Please try again.</p>
         {% endif %}
 
-        <form method="post" action="{% url django.contrib.auth.views.login %}">{% csrf_token %}
+        <form method="post" action="{% url django.contrib.auth.views.login %}">
+        {% csrf_token %}
         <table>
         <tr>
             <td>{{ form.username.label_tag }}</td>
@@ -898,10 +906,11 @@ 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])
+.. function:: views.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, and sends them the new password
-    in an e-mail.
+    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.
 
     **Optional arguments:**
 
@@ -923,6 +932,11 @@ 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`.
+
     **Template context:**
 
         * ``form``: The form for resetting the user's password.
@@ -1007,8 +1021,8 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
 
 .. class:: PasswordResetForm
 
-    A form for resetting a user's password and e-mailing the new password to
-    them.
+    A form for generating and e-mailing a one-time use link to reset a
+    user's password.
 
 .. class:: SetPasswordForm
 
@@ -1112,7 +1126,7 @@ The permission_required decorator
 Limiting access to generic views
 --------------------------------
 
-To limit access to a :ref:`generic view <ref-generic-views>`, write a thin
+To limit access to a :doc:`generic view </ref/generic-views>`, write a thin
 wrapper around the view, and point your URLconf to your wrapper instead of the
 generic view itself. For example::
 
@@ -1229,13 +1243,13 @@ Methods
 ~~~~~~~
 
 :class:`~django.contrib.auth.models.Permission` objects have the standard
-data-access methods like any other :ref:`Django model <ref-models-instances>`.
+data-access methods like any other :doc:`Django model </ref/models/instances>`.
 
 Authentication data in templates
 ================================
 
 The currently logged-in user and his/her permissions are made available in the
-:ref:`template context <ref-templates-api>` when you use
+:doc:`template context </ref/templates/api>` when you use
 :class:`~django.template.context.RequestContext`.
 
 .. admonition:: Technicality
@@ -1324,7 +1338,7 @@ Messages
 
 .. deprecated:: 1.2
    This functionality will be removed in Django 1.4.  You should use the
-   :ref:`messages framework <ref-contrib-messages>` for all new projects and
+   :doc:`messages framework </ref/contrib/messages>` for all new projects and
    begin to update your existing code immediately.
 
 The message system is a lightweight way to queue messages for given users.
@@ -1359,7 +1373,7 @@ a playlist::
 
 When you use :class:`~django.template.context.RequestContext`, the currently
 logged-in user and his/her messages are made available in the
-:ref:`template context <ref-templates-api>` as the template variable
+:doc:`template context </ref/templates/api>` as the template variable
 ``{{ messages }}``. Here's an example of template code that displays messages:
 
 .. code-block:: html+django
@@ -1374,14 +1388,14 @@ logged-in user and his/her messages are made available in the
 
 .. versionchanged:: 1.2
    The ``messages`` template variable uses a backwards compatible method in the
-   :ref:`messages framework <ref-contrib-messages>` to retrieve messages from
+   :doc:`messages framework </ref/contrib/messages>` to retrieve messages from
    both the user ``Message`` model and from the new framework.  Unlike in
    previous revisions, the messages will not be erased unless they are actually
    displayed.
 
 Finally, note that this messages framework only works with users in the user
 database. To send messages to anonymous users, use the
-:ref:`messages framework <ref-contrib-messages>`.
+:doc:`messages framework </ref/contrib/messages>`.
 
 .. _authentication-backends:
 
@@ -1402,7 +1416,7 @@ plug in other authentication sources. You can override Django's default
 database-based scheme, or you can use the default system in tandem with other
 systems.
 
-See the :ref:`authentication backend reference <ref-authentication-backends>`
+See the :doc:`authentication backend reference </ref/authbackends>`
 for information on the authentication backends included with Django.
 
 Specifying authentication backends
@@ -1411,9 +1425,9 @@ Specifying authentication backends
 Behind the scenes, Django maintains a list of "authentication backends" that it
 checks for authentication. When somebody calls
 :func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log
-a user in` above -- Django tries authenticating across all of its
-authentication backends. If the first authentication method fails, Django tries
-the second one, and so on, until all backends have been attempted.
+a user in <how-to-log-a-user-in>` above -- Django tries authenticating across
+all of its authentication backends. If the first authentication method fails,
+Django tries the second one, and so on, until all backends have been attempted.
 
 The list of authentication backends to use is specified in the
 :setting:`AUTHENTICATION_BACKENDS` setting. This should be a tuple of Python
@@ -1593,7 +1607,7 @@ object permissions will always return ``False`` or an empty list (depending on
 the check performed).
 
 To enable object permissions in your own
-:ref:`authentication backend <ref-authentication-backends>` you'll just have
+:doc:`authentication backend </ref/authbackends>` you'll just have
 to allow passing an ``obj`` parameter to the permission methods and set the
 ``supports_object_permissions`` class attribute to ``True``.