Fixed #24253 -- Documented staff_member_required decorator.

2 files changed, 35 insertions, 1 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index d638f36859..d6b88f5f38 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -2717,3 +2717,29 @@ The action in the examples above match the last part of the URL names for
 :class:`ModelAdmin` instances described above. The ``opts`` variable can be any
 object which has an ``app_label`` and ``model_name`` attributes and is usually
 supplied by the admin views for the current model.
+
+.. currentmodule:: django.contrib.admin.views.decorators
+
+The ``staff_member_required`` decorator
+=======================================
+
+.. function:: staff_member_required([redirect_field_name=REDIRECT_FIELD_NAME, login_url='admin:login'])
+
+    This decorator is used on the admin views that require authorization. A
+    view decorated with this function will having the following behavior:
+
+    * If the user is logged in, is a staff member (``User.is_staff=True``), and
+      is active (``User.is_active=True``), execute the view normally.
+
+    * Otherwise, the request will be redirected to the URL specified by the
+      ``login_url`` parameter, with the originally requested path in a query
+      string variable specified by ``redirect_field_name``. For example:
+      ``/admin/login/?next=/admin/polls/question/3/``.
+
+    Example usage::
+
+        from django.contrib.admin.views.decorators import staff_member_required
+
+        @staff_member_required
+        def my_view(request):
+            ...
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index 156746e3c2..0cea34ed1a 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -485,7 +485,15 @@ The login_required decorator
 
 .. note::
 
-    The login_required decorator does NOT check the is_active flag on a user.
+    The ``login_required`` decorator does NOT check the ``is_active`` flag on a
+    user.
+
+.. seealso::
+
+    If you are writing custom views for Django's admin (or need the same
+    authorization check that the built-in views use), you may find the
+    :func:`django.contrib.admin.views.decorators.staff_member_required`
+    decorator a useful alternative to ``login_required()``.
 
 Limiting access to logged-in users that pass a test
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~