Deprecated TEMPLATE_LOADERS.

11 files changed, 76 insertions, 43 deletions

diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt
index 24b33adc35..e4b434714e 100644
--- a/docs/howto/deployment/checklist.txt
+++ b/docs/howto/deployment/checklist.txt
@@ -178,8 +178,8 @@ processing time.
 
 This helps a lot on virtualized hosts with limited network performance.
 
-:setting:`TEMPLATE_LOADERS`
----------------------------
+:setting:`TEMPLATES`
+--------------------
 
 Enabling the cached template loader often improves performance drastically, as
 it avoids compiling each template every time it needs to be rendered. See the
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 415b61eafd..f3d50d3c90 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -90,6 +90,7 @@ details on these changes.
 * The following settings will be removed:
 
   * ``ALLOWED_INCLUDE_ROOTS``
+  * ``TEMPLATE_LOADERS``
   * ``TEMPLATE_STRING_IF_INVALID``
 
 * The backwards compatibility alias ``django.template.loader.BaseLoader`` will
diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt
index b428c9afb8..c4590abf23 100644
--- a/docs/intro/tutorial03.txt
+++ b/docs/intro/tutorial03.txt
@@ -314,12 +314,13 @@ creating a template that the view can use.
 First, create a directory called ``templates`` in your ``polls`` directory.
 Django will look for templates in there.
 
-Django's :setting:`TEMPLATE_LOADERS` setting contains a list of callables that
-know how to import templates from various sources. One of the defaults is
-:class:`django.template.loaders.app_directories.Loader` which looks for a
-"templates" subdirectory in each of the :setting:`INSTALLED_APPS` - this is how
-Django knows to find the polls templates even though we didn't modify
-:setting:`TEMPLATE_DIRS`, as we did in :ref:`Tutorial 2
+Your project's :setting:`TEMPLATES` setting describes how Django will load and
+render templates. The default settings file configures a ``DjangoTemplates``
+backend whose :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` option is set to
+``True``. By convention ``DjangoTemplates`` looks for a "templates"
+subdirectory in each of the :setting:`INSTALLED_APPS`. This is how Django
+knows to find the polls templates even though we didn't modify the
+:setting:`DIRS <TEMPLATES-DIRS>` option, as we did in :ref:`Tutorial 2
 <ref-customizing-your-projects-templates>`.
 
 .. admonition:: Organizing templates
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index a6a315cc88..55dfe08f17 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -2337,8 +2337,9 @@ directory.
 
 In order to override one or more of them, first create an ``admin`` directory
 in your project's ``templates`` directory. This can be any of the directories
-you specified in :setting:`TEMPLATE_DIRS`. If you have customized the
-:setting:`TEMPLATE_LOADERS` setting, be sure
+you specified in the :setting:`DIRS <TEMPLATES-DIRS>` option of the
+``DjangoTemplates`` backend in the :setting:`TEMPLATES` setting. If you have
+customized the ``'loaders'`` option, be sure
 ``'django.template.loaders.filesystem.Loader'`` appears before
 ``'django.template.loaders.app_directories.Loader'`` so that your custom
 templates will be found by the template loading system before those that are
diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt
index 8279d8e93e..b28b9b463d 100644
--- a/docs/ref/contrib/sitemaps.txt
+++ b/docs/ref/contrib/sitemaps.txt
@@ -34,9 +34,9 @@ To install the sitemap app, follow these steps:
 1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS`
    setting.
 
-2. Make sure ``'django.template.loaders.app_directories.Loader'``
-   is in your :setting:`TEMPLATE_LOADERS` setting. It's in there by default,
-   so you'll only need to change this if you've changed that setting.
+2. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates``
+   backend whose ``APP_DIRS`` options is set to ``True``. It's in there by
+   default, so you'll only need to change this if you've changed that setting.
 
 3. Make sure you've installed the
    :mod:`sites framework <django.contrib.sites>`.
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index dd01e9e1cd..ae387023e7 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2439,6 +2439,11 @@ Default::
      ('django.template.loaders.filesystem.Loader',
       'django.template.loaders.app_directories.Loader')
 
+.. deprecated:: 1.8
+
+    Set the ``'loaders'`` option in the :setting:`OPTIONS <TEMPLATES-OPTIONS>`
+    of a ``DjangoTemplates`` backend instead.
+
 A tuple of template loader classes, specified as strings. Each ``Loader`` class
 knows how to import templates from a particular source. Optionally, a tuple can be
 used instead of a string. The first item in the tuple should be the ``Loader``’s
diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt
index 5aacb2bc09..7ab29ab276 100644
--- a/docs/ref/templates/api.txt
+++ b/docs/ref/templates/api.txt
@@ -734,9 +734,10 @@ with a few other template loaders, which know how to load templates from other
 sources.
 
 Some of these other loaders are disabled by default, but you can activate them
-by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
-should be a tuple of strings or tuples, where each represents a template loader
-class. Here are the template loaders that come with Django:
+by adding a ``'loaders'`` option to your ``DjangoTemplates`` backend in the
+:setting:`TEMPLATES` setting. ``'loaders'`` should be a list of strings or
+tuples, where each represents a template loader class. Here are the template
+loaders that come with Django:
 
 .. currentmodule:: django.template.loaders
 
@@ -744,8 +745,16 @@ class. Here are the template loaders that come with Django:
 
 .. class:: filesystem.Loader
 
-    Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
-    This loader is enabled by default.
+    Loads templates from the filesystem, according to
+    :setting:`DIRS <TEMPLATES-DIRS>`.
+
+    This loader is enabled by default. However it won't find any templates
+    until you set :setting:`DIRS <TEMPLATES-DIRS>` to a non-empty list::
+
+        TEMPLATES = [{
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+        }]
 
 ``django.template.loaders.app_directories.Loader``
 
@@ -782,7 +791,14 @@ class. Here are the template loaders that come with Django:
     it caches a list of which :setting:`INSTALLED_APPS` packages have a
     ``templates`` subdirectory.
 
-    This loader is enabled by default.
+    This loader is enabled if and only if :setting:`APP_DIRS
+    <TEMPLATES-APP_DIRS>` is set::
+
+        TEMPLATES = [{
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'APP_DIRS': True,
+        }]
+
 
 ``django.template.loaders.eggs.Loader``
 
@@ -810,12 +826,18 @@ class. Here are the template loaders that come with Django:
     For example, to enable template caching with the ``filesystem`` and
     ``app_directories`` template loaders you might use the following settings::
 
-        TEMPLATE_LOADERS = (
-            ('django.template.loaders.cached.Loader', (
-                'django.template.loaders.filesystem.Loader',
-                'django.template.loaders.app_directories.Loader',
-            )),
-        )
+        TEMPLATES = [{
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'OPTIONS': {
+                'loaders': [
+                    ('django.template.loaders.cached.Loader', (
+                        'django.template.loaders.filesystem.Loader',
+                        'django.template.loaders.app_directories.Loader',
+                    )),
+                ],
+            },
+        }]
 
     .. note::
 
@@ -838,17 +860,21 @@ class. Here are the template loaders that come with Django:
 
     This loader takes a dictionary of templates as its first argument::
 
-        TEMPLATE_LOADERS = (
-            ('django.template.loaders.locmem.Loader', {
-                'index.html': 'content here',
-            }),
-        )
+        TEMPLATES = [{
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'OPTIONS': {
+                'loaders': [
+                    ('django.template.loaders.locmem.Loader', {
+                        'index.html': 'content here',
+                    }),
+                ],
+            },
+        }]
 
     This loader is disabled by default.
 
-Django uses the template loaders in order according to the
-:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a
-match.
+Django uses the template loaders in order according to the ``'loaders'``
+option. It uses each loader until a loader finds a match.
 
 .. currentmodule:: django.template
 
diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt
index 422dff10e5..6d06fa49b2 100644
--- a/docs/releases/1.2.txt
+++ b/docs/releases/1.2.txt
@@ -267,9 +267,9 @@ opposed to functions, the only method available until Django 1.1.
 All the template loaders :ref:`shipped with Django <template-loaders>` have
 been ported to the new API but they still implement the function-based API and
 the template core machinery still accepts function-based loaders (builtin or
-third party) so there is no immediate need to modify your
-:setting:`TEMPLATE_LOADERS` setting in existing projects, things will keep
-working if you leave it untouched up to and including the Django 1.3 release.
+third party) so there is no immediate need to modify your ``TEMPLATE_LOADERS``
+setting in existing projects, things will keep working if you leave it
+untouched up to and including the Django 1.3 release.
 
 If you have developed your own custom template loaders we suggest to consider
 porting them to a class-based implementation because the code for backwards
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index d43ab2e51b..0cc074b24b 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -917,7 +917,7 @@ Miscellaneous
   session store always fetches the most current session data.
 
 * Private APIs ``override_template_loaders`` and ``override_with_test_loader``
-  in ``django.test.utils`` were removed. Override ``TEMPLATE_LOADERS`` with
+  in ``django.test.utils`` were removed. Override ``TEMPLATES`` with
   ``override_settings`` instead.
 
 * Warnings from the MySQL database backend are no longer converted to
@@ -1021,6 +1021,7 @@ As a consequence of the multiple template engines refactor, several settings
 are deprecated in favor of :setting:`TEMPLATES`:
 
 * ``ALLOWED_INCLUDE_ROOTS``
+* ``TEMPLATE_LOADERS``
 * ``TEMPLATE_STRING_IF_INVALID``
 
 ``django.core.context_processors``
diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt
index ee2d583dc7..f3d922ab3a 100644
--- a/docs/topics/class-based-views/generic-display.txt
+++ b/docs/topics/class-based-views/generic-display.txt
@@ -136,10 +136,9 @@ bit is just the lowercased version of the model's name.
 
 .. note::
 
-    Thus, when (for example) the
-    :class:`django.template.loaders.app_directories.Loader` template loader is
-    enabled in :setting:`TEMPLATE_LOADERS`, a template location could be:
-    /path/to/project/books/templates/books/publisher_list.html
+    Thus, when (for example) the ``APP_DIRS`` option of a ``DjangoTemplates``
+    backend is set to True in :setting:`TEMPLATES`, a template location could
+    be: /path/to/project/books/templates/books/publisher_list.html
 
 This template will be rendered against a context containing a variable called
 ``object_list`` that contains all the publisher objects. A very simple template
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index d1e06704f2..b986ca2481 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -1303,8 +1303,7 @@ Django itself uses this signal to reset various data:
 Overridden settings              Data reset
 ================================ ========================
 USE_TZ, TIME_ZONE                Databases timezone
-TEMPLATE_CONTEXT_PROCESSORS      Context processors cache
-TEMPLATE_LOADERS                 Template loaders cache
+TEMPLATES                        Template engines
 SERIALIZATION_MODULES            Serializers cache
 LOCALE_PATHS, LANGUAGE_CODE      Default translation and loaded translations
 MEDIA_ROOT, DEFAULT_FILE_STORAGE Default file storage