[5.1.x] Refs #31405 -- Improved LoginRequiredMiddleware documentation.

co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>

Backport of 49815f70e4508ae21135f725da177fc2935de32c from main.

1 files changed, 41 insertions, 14 deletions

diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index ba9bef7e6f..4c7db09947 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -499,26 +499,50 @@ every incoming ``HttpRequest`` object. See :ref:`Authentication in web requests
 
 .. versionadded:: 5.1
 
-Redirects all unauthenticated requests to a login page. For admin views, this
-redirects to the admin login. For all other views, this will redirect to
-:setting:`settings.LOGIN_URL <LOGIN_URL>`. This can be customized by using the
-:func:`~.django.contrib.auth.decorators.login_required` decorator and setting
-``login_url`` or ``redirect_field_name`` for the view. For example::
+Redirects all unauthenticated requests to a login page, except for views
+excluded with :func:`~.django.contrib.auth.decorators.login_not_required`. The
+login page defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>`, but can be
+customized.
+
+Enable this middleware by adding it to the :setting:`MIDDLEWARE` setting
+**after** :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`::
+
+    MIDDLEWARE = [
+        "...",
+        "django.contrib.auth.middleware.AuthenticationMiddleware",
+        "django.contrib.auth.middleware.LoginRequiredMiddleware",
+        "...",
+    ]
+
+Make a view public, allowing unauthenticated requests, with
+:func:`~.django.contrib.auth.decorators.login_not_required`. For example::
+
+       from django.contrib.auth.decorators import login_not_required
+
+
+       @login_not_required
+       def contact_us(request): ...
+
+Customize the login URL or field name for authenticated views with the
+:func:`~.django.contrib.auth.decorators.login_required` decorator to set
+``login_url`` or ``redirect_field_name`` respectively. For example::
+
+    from django.contrib.auth.decorators import login_required
+    from django.utils.decorators import method_decorator
+    from django.views.generic import View
+
+
+    @login_required(login_url="/books/login/", redirect_field_name="redirect_to")
+    def book_dashboard(request): ...
+
 
     @method_decorator(
-        login_required(login_url="/login/", redirect_field_name="redirect_to"),
+        login_required(login_url="/books/login/", redirect_field_name="redirect_to"),
         name="dispatch",
     )
-    class MyView(View):
+    class BookMetrics(View):
         pass
 
-
-    @login_required(login_url="/login/", redirect_field_name="redirect_to")
-    def my_view(request): ...
-
-Views using the :func:`~django.contrib.auth.decorators.login_not_required`
-decorator are exempt from this requirement.
-
 .. admonition:: Ensure that your login view does not require a login.
 
     To prevent infinite redirects, ensure you have
@@ -527,6 +551,9 @@ decorator are exempt from this requirement.
 
 **Methods and Attributes**
 
+Subclass the middleware and override these to customize behavior for
+unauthenticated requests.
+
 .. attribute:: redirect_field_name
 
     Defaults to ``"next"``.