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

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

Backport of 49815f70e4 from main.

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"``.

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
 --------------
 

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.