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

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

Backport of 49815f70e4508ae21135f725da177fc2935de32c from main.

3 files changed, 47 insertions, 17 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"``.
diff --git a/docs/releases/5.1.txt b/docs/releases/5.1.txt
index 40b59eb091..f47fa8bd3f 100644
--- a/docs/releases/5.1.txt
+++ b/docs/releases/5.1.txt
@@ -91,12 +91,15 @@ redirects all unauthenticated requests to a login page. Views can allow
 unauthenticated requests by using the new
 :func:`~django.contrib.auth.decorators.login_not_required` decorator.
 
-The :class:`~django.contrib.auth.middleware.LoginRequiredMiddleware` respects
-the ``login_url`` and ``redirect_field_name`` values set via the
+``LoginRequiredMiddleware`` respects the ``login_url`` and
+``redirect_field_name`` values set via the
 :func:`~.django.contrib.auth.decorators.login_required` decorator, but does not
 support setting ``login_url`` or ``redirect_field_name`` via the
 :class:`~django.contrib.auth.mixins.LoginRequiredMixin`.
 
+To enable this, add ``"django.contrib.auth.middleware.LoginRequiredMiddleware"``
+to your :setting:`MIDDLEWARE` setting.
+
 Minor features
 --------------
 
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index 1d2ea8132d..10401717cf 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -671,7 +671,7 @@ login view, may need to disable this behavior.
 
 .. function:: login_not_required()
 
-    Allows unauthenticated requests without redirecting to the login page when
+    Allows unauthenticated requests to this view when
     :class:`~django.contrib.auth.middleware.LoginRequiredMiddleware` is
     installed.