[1.8.x] Fixed #25397 -- Documented class-based view context variable clash with context processors.

Backport of 494b7986a3e5996d857b085f188a630d1504d9ca from master

3 files changed, 29 insertions, 6 deletions

diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt
index 8296064c15..af9acbfaa7 100644
--- a/docs/ref/class-based-views/mixins-single-object.txt
+++ b/docs/ref/class-based-views/mixins-single-object.txt
@@ -106,20 +106,34 @@ SingleObjectMixin
 
         Returns context data for displaying the list of objects.
 
-        The base implementation of this method requires that the ``object``
+        The base implementation of this method requires that the ``self.object``
         attribute be set by the view (even if ``None``). Be sure to do this if
         you are using this mixin without one of the built-in views that does so.
 
+        It returns a dictionary with these contents:
+
+        * ``object``: The object that this view is displaying
+          (``self.object``).
+        * ``context_object_name``: ``self.object`` will also be stored under
+          the name returned by :meth:`get_context_object_name`, which defaults
+          to the lowercased version of the model name.
+
+        .. admonition:: Context variables override values from template context processors
+
+            Any variables from :meth:`get_context_data` take precedence over
+            context variables from :ref:`context processors
+            <subclassing-context-requestcontext>`. For example, if your view
+            sets the :attr:`model` attribute to
+            :class:`~django.contrib.auth.models.User`, the default context
+            object name of ``user`` would override the ``user`` variable from
+            the :func:`django.contrib.auth.context_processors.auth` context
+            processor. Use :meth:`get_context_object_name` to avoid a clash.
+
     .. method:: get_slug_field()
 
         Returns the name of a slug field to be used to look up by slug. By
         default this simply returns the value of :attr:`slug_field`.
 
-    **Context**
-
-    * ``object``: The object that this view is displaying. If
-      ``context_object_name`` is specified, that variable will also be
-      set in the context, with the same value as ``object``.
 
 SingleObjectTemplateResponseMixin
 ---------------------------------
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 1a739acfa1..5a2fa6a1ec 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -638,9 +638,13 @@ Context processors
 
 Here's what each of the built-in processors does:
 
+.. currentmodule:: django.contrib.auth.context_processors
+
 django.contrib.auth.context_processors.auth
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. function:: auth
+
 If this processor is enabled, every ``RequestContext`` will contain these
 variables:
 
diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt
index ed5c593e95..e21f1772ae 100644
--- a/docs/topics/class-based-views/generic-display.txt
+++ b/docs/topics/class-based-views/generic-display.txt
@@ -237,6 +237,11 @@ template, but you can override it to send more::
     after super if they want to be sure to override all parents. If you're
     having trouble, review the method resolution order of your view.
 
+    Another consideration is that the context data from class-based generic
+    views will override data provided by context processors; see
+    :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data` for
+    an example.
+
 .. _generic-views-list-subsets:
 
 Viewing subsets of objects