Add check and docs for TEMPLATES APP_DIRS=False. (#1498)

* Add check and docs for TEMPLATES APP_DIRS=False.

The toolbar requires at least one DjangoTemplates TEMPLATES
configuration needs to have APP_DIRS set to True.

Author: tim-schilling

debug_toolbar/apps.py

@@ -23,6 +23,20 @@ def check_middleware(app_configs, **kwargs):
     gzip_index = None
     debug_toolbar_indexes = []
 
+    if all(not config.get("APP_DIRS", False) for config in settings.TEMPLATES):
+        errors.append(
+            Warning(
+                "At least one DjangoTemplates TEMPLATES configuration needs "
+                "to have APP_DIRS set to True.",
+                hint=(
+                    "Use APP_DIRS=True for at least one "
+                    "django.template.backends.django.DjangoTemplates "
+                    "backend configuration."
+                ),
+                id="debug_toolbar.W006",
+            )
+        )
+
     # If old style MIDDLEWARE_CLASSES is being used, report an error.
     if settings.is_overridden("MIDDLEWARE_CLASSES"):
         errors.append(

docs/changes.rst

@@ -9,6 +9,8 @@ Next version
   ``django.core.caches`` as a whole. The ``middleware.cache`` is still
   being patched as a whole in order to attempt to catch any cache
   usages before ``enable_instrumentation`` is called.
+* Add check ``W006`` to warn that the toolbar is incompatible with
+  ``TEMPLATES`` settings configurations with ``APP_DIRS`` set to ``False``.
 
 
 3.2.2 (2021-08-14)

docs/checks.rst

@@ -14,3 +14,5 @@ Debug Toolbar setup and configuration:
 * **debug_toolbar.W004**: ``debug_toolbar`` is incompatible with
   ``MIDDLEWARE_CLASSES`` setting.
 * **debug_toolbar.W005**: Setting ``DEBUG_TOOLBAR_PANELS`` is empty.
+* **debug_toolbar.W006**: At least one ``DjangoTemplates`` ``TEMPLATES``
+  configuration needs to have ``APP_DIRS`` set to ``True``.

docs/installation.rst

@@ -37,6 +37,11 @@ Make sure that ``'django.contrib.staticfiles'`` is `set up properly
 
     STATIC_URL = '/static/'
 
+Make sure your ``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.
+
+
 If you're upgrading from a previous version, you should review the
 :doc:`change log <changes>` and look for specific upgrade instructions.
 

tests/test_checks.py

@@ -122,3 +122,37 @@ def test_panels_is_empty(self):
                 )
             ],
         )
+
+    @override_settings(
+        TEMPLATES=[
+            {
+                "BACKEND": "django.template.backends.django.DjangoTemplates",
+                "APP_DIRS": False,
+                "OPTIONS": {
+                    "context_processors": [
+                        "django.template.context_processors.debug",
+                        "django.template.context_processors.request",
+                        "django.contrib.auth.context_processors.auth",
+                        "django.contrib.messages.context_processors.messages",
+                    ]
+                },
+            },
+        ]
+    )
+    def test_templates_is_using_app_dirs_false(self):
+        errors = run_checks()
+        self.assertEqual(
+            errors,
+            [
+                Warning(
+                    "At least one DjangoTemplates TEMPLATES configuration "
+                    "needs to have APP_DIRS set to True.",
+                    hint=(
+                        "Use APP_DIRS=True for at least one "
+                        "django.template.backends.django.DjangoTemplates "
+                        "backend configuration."
+                    ),
+                    id="debug_toolbar.W006",
+                )
+            ],
+        )