[1.7.x] Fixed #21661 -- Expanded authentication views documentation

Backport of eb9b7abb833a6d317e355265552d47e0d8f24af8 from master.

1 files changed, 69 insertions, 9 deletions

diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index 845e69da5c..89af55f101 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -664,18 +664,78 @@ Django provides several views that you can use for handling login, logout, and
 password management. These make use of the :ref:`stock auth forms
 <built-in-auth-forms>` but you can pass in your own forms as well.
 
-Django provides no default template for the authentication views - however the
-template context is documented for each view below.
+Django provides no default template for the authentication views. You should
+create your own templates for the views you want to use. The template context
+is documented in each view, see :ref:`all-authentication-views`.
 
-The built-in views all return
-a :class:`~django.template.response.TemplateResponse` instance, which allows
-you to easily customize the response data before rendering.  For more details,
-see the :doc:`TemplateResponse documentation </ref/template-response>`.
+.. _using-the-views:
 
-Most built-in authentication views provide a URL name for easier reference. See
-:doc:`the URL documentation </topics/http/urls>` for details on using named URL
-patterns.
+Using the views
+~~~~~~~~~~~~~~~
 
+There are different methods to implement these views in your project. The
+easiest way is to include the provided URLconf in ``django.contrib.auth.urls``
+in your own URLconf, for example::
+
+    urlpatterns = [
+        url('^', include('django.contrib.auth.urls'))
+    ]
+
+This will include the following URL patterns::
+
+    ^login/$ [name='login']
+    ^logout/$ [name='logout']
+    ^password_change/$ [name='password_change']
+    ^password_change/done/$ [name='password_change_done']
+    ^password_reset/$ [name='password_reset']
+    ^password_reset/done/$ [name='password_reset_done']
+    ^reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$ [name='password_reset_confirm']
+    ^reset/done/$ [name='password_reset_complete']
+
+The views provide a URL name for easier reference. See :doc:`the URL
+documentation </topics/http/urls>` for details on using named URL patterns.
+
+If you want more control over your URLs, you can reference a specific view in
+your URLconf::
+
+    urlpatterns = [
+        url('^change-password/', 'django.contrib.auth.views.password_change')
+    ]
+
+The views have optional arguments you can use to alter the behavior of the
+view. For example, if you want to change the template name a view uses, you can
+provide the ``template_name`` argument. A way to do this is to provide keyword
+arguments in the URLconf, these will be passed on to the view. For example::
+
+    urlpatterns = [
+        url(
+            '^change-password/',
+            'django.contrib.auth.views.password_change',
+            {'template_name': 'change-password.html'}
+        )
+    ]
+
+All views return a :class:`~django.template.response.TemplateResponse`
+instance, which allows you to easily customize the response data before
+rendering. A way to do this is to wrap a view in your own view::
+
+    from django.contrib.auth import views
+
+    def change_password(request):
+        template_response = views.password_change(request)
+        # Do something with `template_response`
+        return template_response
+
+For more details, see the :doc:`TemplateResponse documentation
+</ref/template-response>`.
+
+.. _all-authentication-views:
+
+All authentication views
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a list with all the views ``django.contrib.auth`` provides. For
+implementation details see :ref:`using-the-views`.
 
 .. function:: login(request, [template_name, redirect_field_name, authentication_form, current_app, extra_context])