[Django] #25386: Unclear documentation for default debug setting for DjangoTemplates engine
Django
-------------------------------------+-------------------------------------
Reporter: lightstrike | Owner: lightstrike
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 1.8
Severity: Normal | Keywords: template, template
| engine
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
In 1.8, the TEMPLATE_DEBUG setting is deprecated in favor of setting
'debug' as part of the OPTIONS sub-setting in a backend in TEMPLATES.
In a couple parts of the documentation, it is stated that the default
'debug' setting for DjangoTemplates engine is False:
* [https://docs.djangoproject.com/en/dev/ref/templates/api/#configuring-
an-engine Template API]
* [https://docs.djangoproject.com/en/1.8/ref/settings/#template-debug
Settings:TEMPLATE_DEBUG]
In reality, the default is
[https://github.com/django/django/blob/aaacaeb0963c406c4fe6f68c6ae51f4a65878250/django/template/backends/django.py#L28
apparently set according to settings.DEBUG].
I suggest clarifying the documentation to state that the default debug
setting is equal to settings.DEBUG (which is True by default). It would be
additionally helpful to link to the possible options one can set in a
template engine on the
[https://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-
TEMPLATES-OPTIONS main settings page].
--
Ticket URL: <https://code.djangoproject.com/ticket/25386>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: lightstrike | Owner:
Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: template, template | Triage Stage:
engine | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Comment:
The default value for `DjangoTemplates` is
[https://docs.djangoproject.com/en/dev/topics/templates/#django.template.backends.django.DjangoTemplates
documented elsewhere] from the places you linked. I think those other
places are correct, but please clarify if you believe otherwise.
I'll propose this patch to address your last point:
{{{#!diff
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index f4e5c37..d2582c6 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2324,7 +2324,10 @@ OPTIONS
Default: ``{}`` (Empty dict)
Extra parameters to pass to the template backend. Available parameters
vary
-depending on the template backend.
+depending on the template backend. See
+:class:`~django.template.backends.django.DjangoTemplates` and
+:class:`~django.template.backends.jinja2.Jinja2` for the options of the
+built-in backends.
.. setting:: TEMPLATE_CONTEXT_PROCESSORS
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage:
engine | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: new => assigned
* owner: lightstrike => dhanus
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:2>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage:
engine | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"f3e5a746469401a16939de0fc17fed584ced2118" f3e5a74]:
{{{
#!CommitTicketReference repository=""
revision="f3e5a746469401a16939de0fc17fed584ced2118"
Refs #25386 -- Added links to the OPTIONS of the built-in template
backends.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage:
engine | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"2955dfdeca271cd8b4899455b44fe77809ebccb9" 2955dfd]:
{{{
#!CommitTicketReference repository=""
revision="2955dfdeca271cd8b4899455b44fe77809ebccb9"
[1.8.x] Refs #25386 -- Added links to the OPTIONS of the built-in template
backends.
Backport of f3e5a746469401a16939de0fc17fed584ced2118 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:4>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage: Accepted
engine |
Has patch: 0 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
Comment:
Accepting on the basis that the "Configuration an Engine" section of the
docs could use an upfront warning that if you're simply using
`DjangoTemplates`, this isn't the documentation you're looking for (as
described on the [https://github.com/django/django/pull/5273 pull
request]).
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:5>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage: Accepted
engine |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/5347 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:6>
Django
-------------------------------------+-------------------------------------
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage: Accepted
engine |
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"2634f606d55b63511ab1c50c4fad2d52fbda1b19" 2634f60]:
{{{
#!CommitTicketReference repository=""
revision="2634f606d55b63511ab1c50c4fad2d52fbda1b19"
Fixed #25386 -- Warned about differences between Engine and
DjangoTemplates.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:7>
Django
-------------------------------------+-------------------------------------
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 1.8
Keywords: template, template | Triage Stage: Accepted
engine |
Has patch: 1 | Needs documentation: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In [changeset:"e7064df44f38c60a4e2aa1dfc41d544b1a77ca65" e7064df]:
{{{
#!CommitTicketReference repository=""
revision="e7064df44f38c60a4e2aa1dfc41d544b1a77ca65"
[1.8.x] Fixed #25386 -- Warned about differences between Engine and
DjangoTemplates.
Backport of 2634f606d55b63511ab1c50c4fad2d52fbda1b19 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25386#comment:8>