Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#25386 closed Cleanup/optimization (fixed)

Unclear documentation for default debug setting for DjangoTemplates engine

Reported by: lightstrike Owned by: Deborah
Component: Documentation Version: 1.8
Severity: Normal Keywords: template, template engine
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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:

In reality, the default is 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 main settings page.

Change History (8)

comment:1 Changed 6 years ago by Tim Graham

The default value for DjangoTemplates is 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:

  • docs/ref/settings.txt

    diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
    index f4e5c37..d2582c6 100644
    a b OPTIONS 
    23242324Default: ``{}`` (Empty dict)
    23252325
    23262326Extra parameters to pass to the template backend. Available parameters vary
    2327 depending on the template backend.
     2327depending on the template backend. See
     2328:class:`~django.template.backends.django.DjangoTemplates` and
     2329:class:`~django.template.backends.jinja2.Jinja2` for the options of the
     2330built-in backends.
    23282331
    23292332.. setting:: TEMPLATE_CONTEXT_PROCESSORS
    23302333

comment:2 Changed 6 years ago by Deborah

Owner: changed from lightstrike to Deborah
Status: newassigned

comment:3 Changed 6 years ago by Tim Graham <timograham@…>

In f3e5a74:

Refs #25386 -- Added links to the OPTIONS of the built-in template backends.

comment:4 Changed 6 years ago by Tim Graham <timograham@…>

In 2955dfd:

[1.8.x] Refs #25386 -- Added links to the OPTIONS of the built-in template backends.

Backport of f3e5a746469401a16939de0fc17fed584ced2118 from master

comment:5 Changed 6 years ago by Tim Graham

Triage Stage: UnreviewedAccepted

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 pull request).

comment:6 Changed 6 years ago by Tim Graham

Has patch: set

comment:7 Changed 6 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 2634f60:

Fixed #25386 -- Warned about differences between Engine and DjangoTemplates.

comment:8 Changed 6 years ago by Tim Graham <timograham@…>

In e7064df:

[1.8.x] Fixed #25386 -- Warned about differences between Engine and DjangoTemplates.

Backport of 2634f606d55b63511ab1c50c4fad2d52fbda1b19 from master

Note: See TracTickets for help on using tickets.
Back to Top