Deprecated TEMPLATE_DIRS.

docs/internals/deprecation.txt

@@ -90,6 +90,7 @@ details on these changes.
 * The following settings will be removed:
 
   * ``ALLOWED_INCLUDE_ROOTS``
+  * ``TEMPLATE_DIRS``
   * ``TEMPLATE_LOADERS``
   * ``TEMPLATE_STRING_IF_INVALID``
 

docs/intro/overview.txt

@@ -254,8 +254,8 @@ The code above loads the ``news/year_archive.html`` template.
 
 Django has a template search path, which allows you to minimize redundancy among
 templates. In your Django settings, you specify a list of directories to check
-for templates with :setting:`TEMPLATE_DIRS`. If a template doesn't exist in the
-first directory, it checks the second, and so on.
+for templates with :setting:`DIRS <TEMPLATES-DIRS>`. If a template doesn't exist
+in the first directory, it checks the second, and so on.
 
 Let's say the ``news/year_archive.html`` template was found. Here's what that
 might look like:

docs/intro/tutorial02.txt

@@ -488,15 +488,32 @@ whatever user your server runs.) However, keeping your templates within the
 project is a good convention to follow.
 
 Open your settings file (:file:`mysite/settings.py`, remember) and add a
-:setting:`TEMPLATE_DIRS` setting:
+:setting:`DIRS <TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting:
 
 .. snippet::
     :filename: mysite/settings.py
 
-    TEMPLATE_DIRS = [os.path.join(BASE_DIR, 'templates')]
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'DIRS': [os.path.join(BASE_DIR, 'templates')],
+            'APP_DIRS': True,
+            'OPTIONS': {
+                'context_processors': [
+                    'django.template.context_processors.debug',
+                    'django.template.context_processors.i18n',
+                    'django.template.context_processors.tz',
+                    'django.template.context_processors.media',
+                    'django.template.context_processors.static',
+                    'django.contrib.auth.context_processors.auth',
+                    'django.contrib.messages.context_processors.messages',
+                ],
+            },
+        },
+    ]
 
-:setting:`TEMPLATE_DIRS` is an iterable of filesystem directories to check when
-loading Django templates; it's a search path.
+:setting:`DIRS <TEMPLATES-DIRS>` is a list of filesystem directories to check
+when loading Django templates; it's a search path.
 
 Now create a directory called ``admin`` inside ``templates``, and copy the
 template ``admin/base_site.html`` from within the default Django admin
@@ -547,10 +564,11 @@ changes.
 Customizing your *application's* templates
 ------------------------------------------
 
-Astute readers will ask: But if :setting:`TEMPLATE_DIRS` was empty by default,
-how was Django finding the default admin templates? The answer is that, by
-default, Django automatically looks for a ``templates/`` subdirectory within
-each application package, for use as a fallback (don't forget that
+Astute readers will ask: But if :setting:`DIRS <TEMPLATES-DIRS>` was empty by
+default, how was Django finding the default admin templates? The answer is
+that, since :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` is set to ``True``,
+Django automatically looks for a ``templates/`` subdirectory within each
+application package, for use as a fallback (don't forget that
 ``django.contrib.admin`` is an application).
 
 Our poll application is not very complex and doesn't need custom admin

docs/ref/contrib/sites.txt

@@ -209,8 +209,8 @@ subscribing to LJWorld.com alerts." Same goes for the email's message body.
 
 Note that an even more flexible (but more heavyweight) way of doing this would
 be to use Django's template system. Assuming Lawrence.com and LJWorld.com have
-different template directories (:setting:`TEMPLATE_DIRS`), you could simply
-farm out to the template system like so::
+different template directories (:setting:`DIRS <TEMPLATES-DIRS>`), you could
+simply farm out to the template system like so::
 
     from django.core.mail import send_mail
     from django.template import loader, Context

docs/ref/settings.txt

@@ -2422,6 +2422,11 @@ TEMPLATE_DIRS
 
 Default: ``()`` (Empty tuple)
 
+.. deprecated:: 1.8
+
+    Set the :setting:`DIRS <TEMPLATES-DIRS>` option of a ``DjangoTemplates``
+    backend instead.
+
 List of locations of the template source files searched by
 :class:`django.template.loaders.filesystem.Loader`, in search order.
 

docs/ref/templates/api.txt

@@ -620,21 +620,30 @@ specified as a **template directory**.
 
 Django searches for template directories in a number of places, depending on
 your template-loader settings (see "Loader types" below), but the most basic
-way of specifying template directories is by using the :setting:`TEMPLATE_DIRS`
-setting.
+way of specifying template directories is by using the :setting:`DIRS
+<TEMPLATES-DIRS>` option.
 
-The TEMPLATE_DIRS setting
-~~~~~~~~~~~~~~~~~~~~~~~~~
+The DIRS option
+~~~~~~~~~~~~~~~
 
-Tell Django what your template directories are by using the
-:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a
-list or tuple of strings that contain full paths to your template
-directory(ies). Example::
+.. versionchanged:: 1.8
 
-    TEMPLATE_DIRS = (
-        "/home/html/templates/lawrence.com",
-        "/home/html/templates/default",
-    )
+    This value used to be defined by the ``TEMPLATE_DIRS`` setting.
+
+Tell Django what your template directories are by using the :setting:`DIRS
+<TEMPLATES-DIRS>` option in the :setting:`TEMPLATES` setting in your settings
+file. This should be set to a list of strings that contain full paths to your
+template directory(ies). Example::
+
+    TEMPLATES = [
+        {
+            'BACKEND': 'django.template.backends.django.DjangoTemplates',
+            'DIRS': [
+                '/home/html/templates/lawrence.com',
+                '/home/html/templates/default',
+            ],
+        },
+    ]
 
 Your templates can go anywhere you want, as long as the directories and
 templates are readable by the Web server. They can have any extension you want,
@@ -679,8 +688,8 @@ The Python API
        The ``dirs`` parameter was deprecated.
 
 For example, if you call ``get_template('story_detail.html')`` and have the
-above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for,
-in order:
+above :setting:`DIRS <TEMPLATES-DIRS>` option, here are the files Django will
+look for, in order:
 
 * ``/home/html/templates/lawrence.com/story_detail.html``
 * ``/home/html/templates/default/story_detail.html``
@@ -718,8 +727,8 @@ To load a template that's within a subdirectory, just use a slash, like so::
 
     get_template('news/story_detail.html')
 
-Using the same :setting:`TEMPLATE_DIRS` setting from above, this example
-``get_template()`` call will attempt to load the following templates:
+Using the same :setting:`DIRS <TEMPLATES-DIRS>` option from above, this
+example ``get_template()`` call will attempt to load the following templates:
 
 * ``/home/html/templates/lawrence.com/news/story_detail.html``
 * ``/home/html/templates/default/news/story_detail.html``
@@ -976,7 +985,7 @@ in :ref:`settings-without-django-settings-module`. Simply import the appropriate
 pieces of the templating system and then, *before* you call any of the
 templating functions, call :func:`django.conf.settings.configure()` with any
 settings you wish to specify. You might want to consider setting at least
-:setting:`TEMPLATE_DIRS` (if you're going to use template loaders),
+:setting:`DIRS <TEMPLATES-DIRS>` (if you're going to use template loaders),
 :setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine)
 and :setting:`TEMPLATE_DEBUG`. If you plan to use the :ttag:`url` template tag,
 you will also need to set the :setting:`ROOT_URLCONF` setting. All available

docs/releases/1.7.txt

@@ -853,7 +853,7 @@ Templates
   rendering of a template.
 
 * The following functions now accept a ``dirs`` parameter which is a list or
-  tuple to override :setting:`TEMPLATE_DIRS`:
+  tuple to override ``TEMPLATE_DIRS``:
 
   * :func:`django.template.loader.get_template()`
   * :func:`django.template.loader.select_template()`

docs/releases/1.8.txt

@@ -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_DIRS``
 * ``TEMPLATE_LOADERS``
 * ``TEMPLATE_STRING_IF_INVALID``
 
@@ -1249,7 +1250,7 @@ templates through the ``context`` dict.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following functions will no longer accept a ``dirs`` parameter to override
-:setting:`TEMPLATE_DIRS` in Django 2.0:
+``TEMPLATE_DIRS`` in Django 2.0:
 
 * :func:`django.template.loader.get_template()`
 * :func:`django.template.loader.select_template()`

docs/topics/settings.txt

@@ -13,9 +13,9 @@ A settings file is just a Python module with module-level variables.
 
 Here are a couple of example settings::
 
+    ALLOWED_HOSTS = ['www.example.com']
     DEBUG = False
     DEFAULT_FROM_EMAIL = 'webmaster@example.com'
-    TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
 
 .. note::
 
@@ -188,8 +188,7 @@ Example::
 
     from django.conf import settings
 
-    settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
-        TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
+    settings.configure(DEBUG=True, TEMPLATE_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