[1.8.x] Fixed #25169 -- Documented stacking of permission_required and login_required.

Backport of 9788625277b85596302bbf2c39cf829b7a766a4f from master

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index c60e83df30..146cf8773d 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -592,6 +592,17 @@ The permission_required decorator
     (HTTP Forbidden) view<http_forbidden_view>` instead of redirecting to the
     login page.
 
+    If you want to use ``raise_exception`` but also give your users a chance to
+    login first, you can add the
+    :func:`~django.contrib.auth.decorators.login_required` decorator::
+
+        from django.contrib.auth.decorators import login_required, permission_required
+
+        @permission_required('polls.can_vote', raise_exception=True)
+        @login_required
+        def my_view(request):
+            ...
+
     .. versionchanged:: 1.7
 
         The :func:`~django.contrib.auth.decorators.permission_required`