[1.8.x] Deprecated TEMPLATE_DEBUG setting.

Backport of 15b711b from master.

10 files changed, 23 insertions, 15 deletions

diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt
index b13c8cb81a..d8fde58ffd 100644
--- a/docs/howto/custom-template-tags.txt
+++ b/docs/howto/custom-template-tags.txt
@@ -772,10 +772,9 @@ Notes:
 * The ``render()`` method is where the work actually happens.
 
 * ``render()`` should generally fail silently, particularly in a production
-  environment where :setting:`DEBUG` and :setting:`TEMPLATE_DEBUG` are
-  ``False``. In some cases however, particularly if :setting:`TEMPLATE_DEBUG` is
-  ``True``, this method may raise an exception to make debugging easier. For
-  example, several core tags raise ``django.template.TemplateSyntaxError``
+  environment. In some cases however, particularly if ``context.engine.debug``
+  is ``True``, this method may raise an exception to make debugging easier.
+  For example, several core tags raise ``django.template.TemplateSyntaxError``
   if they receive the wrong number or type of arguments.
 
 Ultimately, this decoupling of compilation and rendering results in an
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 49a3982239..beec417f95 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -101,6 +101,7 @@ details on these changes.
 
   * ``ALLOWED_INCLUDE_ROOTS``
   * ``TEMPLATE_CONTEXT_PROCESSORS``
+  * ``TEMPLATE_DEBUG``
   * ``TEMPLATE_DIRS``
   * ``TEMPLATE_LOADERS``
   * ``TEMPLATE_STRING_IF_INVALID``
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index db2850da6d..4744098754 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2421,6 +2421,11 @@ TEMPLATE_DEBUG
 
 Default: ``False``
 
+.. deprecated:: 1.8
+
+    Set the ``'debug'`` option in the :setting:`OPTIONS <TEMPLATES-OPTIONS>`
+    of a ``DjangoTemplates`` backend instead.
+
 A boolean that turns on/off template debug mode. If this is ``True``, the fancy
 error page will display a detailed report for any exception raised during
 template rendering. This report contains the relevant snippet of the template,
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 9faca5b9e1..b6d5c9e9c1 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -946,7 +946,7 @@ Template origin
 When an :class:`~django.template.Engine` is initialized with ``debug=True``,
 its templates have an ``origin`` attribute depending on the source they are
 loaded from. For engines initialized by Django, ``debug`` defaults to the
-value of :setting:`TEMPLATE_DEBUG`.
+value of :setting:`DEBUG`.
 
 .. class:: loader.LoaderOrigin
 
diff --git a/docs/ref/templates/upgrading.txt b/docs/ref/templates/upgrading.txt
index c7b07464b0..98778c36ba 100644
--- a/docs/ref/templates/upgrading.txt
+++ b/docs/ref/templates/upgrading.txt
@@ -10,7 +10,7 @@ The :setting:`TEMPLATES` settings
 =================================
 
 A new setting was introduced in Django 1.8: :setting:`TEMPLATES`. All existing
-template-related settings except :setting:`TEMPLATE_DEBUG` were deprecated.
+template-related settings were deprecated.
 
 During the deprecation period, Django will create a backwards-compatible
 :setting:`TEMPLATES` based on the ``TEMPLATE_*`` settings if you don't define
@@ -85,9 +85,13 @@ If your settings module defines ``ALLOWED_INCLUDE_ROOTS`` or
 ``'allowed_include_roots'`` and ``'string_if_invalid'`` keys in the
 ``'OPTIONS'`` dictionary.
 
+If it sets ``TEMPLATE_DEBUG`` to a value that differs from :setting:`DEBUG`,
+include that value under the ``'debug'`` key in ``'OPTIONS'``.
+
 Once you have defined :setting:`TEMPLATES`, you can safely remove
-``ALLOWED_INCLUDE_ROOTS``, ``TEMPLATE_CONTEXT_PROCESSORS``, ``TEMPLATE_DIRS``,
-``TEMPLATE_LOADERS``, and ``TEMPLATE_STRING_IF_INVALID``.
+``ALLOWED_INCLUDE_ROOTS``, ``TEMPLATE_CONTEXT_PROCESSORS``,
+``TEMPLATE_DEBUG``, ``TEMPLATE_DIRS``, ``TEMPLATE_LOADERS``, and
+``TEMPLATE_STRING_IF_INVALID``.
 
 If you are overriding some of these settings in tests, you should override the
 entire :setting:`TEMPLATES` setting instead.
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 811b800bb0..f4f85d0154 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -437,7 +437,7 @@ For example:
 No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In previous versions of Django, whenever the :setting:`TEMPLATE_DEBUG` setting
+In previous versions of Django, whenever the ``TEMPLATE_DEBUG`` setting
 was ``True``, any exception raised during template rendering (even exceptions
 unrelated to template syntax) were wrapped in ``TemplateSyntaxError`` and
 re-raised. This was done in order to provide detailed template source location
@@ -446,7 +446,7 @@ information in the debug 500 page.
 In Django 1.4, exceptions are no longer wrapped. Instead, the original
 exception is annotated with the source information. This means that catching
 exceptions from template rendering is now consistent regardless of the value of
-:setting:`TEMPLATE_DEBUG`, and there's no need to catch and unwrap
+``TEMPLATE_DEBUG``, and there's no need to catch and unwrap
 ``TemplateSyntaxError`` in order to catch other errors.
 
 ``truncatechars`` template filter
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index f4a2c5462b..052c073df9 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -846,7 +846,7 @@ Templates
 * It is now possible to :ttag:`include` templates recursively.
 
 * Template objects now have an origin attribute set when
-  :setting:`TEMPLATE_DEBUG` is ``True``. This allows template origins to be
+  ``TEMPLATE_DEBUG`` is ``True``. This allows template origins to be
   inspected and logged outside of the ``django.template`` infrastructure.
 
 * ``TypeError`` exceptions are no longer silenced when raised during the
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index ff3683a4b0..331998c0f3 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -1262,6 +1262,7 @@ are deprecated in favor of :setting:`TEMPLATES`:
 
 * ``ALLOWED_INCLUDE_ROOTS``
 * ``TEMPLATE_CONTEXT_PROCESSORS``
+* ``TEMPLATE_DEBUG``
 * ``TEMPLATE_DIRS``
 * ``TEMPLATE_LOADERS``
 * ``TEMPLATE_STRING_IF_INVALID``
diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt
index e84b344e53..bf6a7a75d5 100644
--- a/docs/topics/settings.txt
+++ b/docs/topics/settings.txt
@@ -188,7 +188,7 @@ Example::
 
     from django.conf import settings
 
-    settings.configure(DEBUG=True, TEMPLATE_DEBUG=True)
+    settings.configure(DEBUG=True)
 
 Pass ``configure()`` as many keyword arguments as you'd like, with each keyword
 argument representing a setting and its value. Each argument name should be all
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 920637de44..b60a7813e0 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -364,9 +364,7 @@ applications. This generic name was kept for backwards-compatibility.
   exception raised during template rendering. This report contains the
   relevant snippet of the template with the appropriate line highlighted.
 
-  It defaults to the value of the :setting:`TEMPLATE_DEBUG` setting. The
-  setting is convenient for toggling template debug mode globally rather than
-  on a per-engine basis.
+  It defaults to the value of the :setting:`DEBUG` setting.
 
 * ``'loaders'``: a list of dotted Python paths to template loader classes.
   Each ``Loader`` class knows how to import templates from a particular