[Django] #25010: TEMPLATES settings documentation is either wrong or just confusing
Django
---------------------------------+--------------------
Reporter: danielquinn | Owner: nobody
Type: Bug | Status: new
Component: Template system | Version: 1.8
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
---------------------------------+--------------------
The documentation for the `TEMPLATES` setting
https://docs.djangoproject.com/en/1.8/ref/settings/#templates says that
`APP_DIR` defines whether or not Django should source templates from the
`templates` directory inside each app directory. In the simple example
given, `APP_DIR` is set to `True`, which is a little weird because this is
the default setup you get when you run `startproject`.
However, further down in the same section, the default for `APP_DIR` is
defined as `False`, so when I first read this, I thought that I needed to
use the example snippet to turn on what was already the default behaviour.
It's all very confusing.
To fix this, I think the best option would be to:
* Document that the default for `APP_DIR` is True (unless this isn't the
case and I'm missing something)
* Modify the example to do something other than the default behaviour.
This part isn't necessary, but coupled with the above problem, none of
this makes sense on first reading.
--
Ticket URL: <https://code.djangoproject.com/ticket/25010>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: danielquinn | Owner: nobody
Type: Bug | Status: new
Component: Template system | Version: 1.8
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by MoritzS):
* needs_better_patch: => 0
* needs_tests: => 0
* needs_docs: => 0
Comment:
The default for `APP_DIR` being `False` means that it will be `False` if
you don't specify it in your settings.
However the settings that `startproject` creates sets it to `True` because
it's almost always is what you want.
Whether it should be `True` or `False` as default however, is up to
discussion. But I think the reason for it being `False` is that you want
sensible defaults that will always work.
--
Ticket URL: <https://code.djangoproject.com/ticket/25010#comment:1>
Django
--------------------------------------+------------------------------------
Reporter: danielquinn | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* type: Bug => Cleanup/optimization
* has_patch: 0 => 1
* stage: Unreviewed => Accepted
* component: Template system => Documentation
Comment:
Daniel, I've attached a patch. Let us know if you have any other
suggestions besides that.
--
Ticket URL: <https://code.djangoproject.com/ticket/25010#comment:2>
Django
--------------------------------------+------------------------------------
Reporter: danielquinn | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timgraham):
* Attachment "25010.diff" added.
Django
--------------------------------------+------------------------------------
Reporter: danielquinn | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by danielquinn):
I read your patch and I literally just said: "Oh!" This makes *so* much
more sense now. Yes, I think this is probably sufficient.
--
Ticket URL: <https://code.djangoproject.com/ticket/25010#comment:3>
Django
--------------------------------------+------------------------------------
Reporter: danielquinn | Owner: nobody
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: new => closed
* resolution: => fixed
Comment:
In [changeset:"4a6656488893b6a832726cade2d2c5aa04f85ae2" 4a66564]:
{{{
#!CommitTicketReference repository=""
revision="4a6656488893b6a832726cade2d2c5aa04f85ae2"
Fixed #25010 -- Documented APP_DIRS default in startproject's settings.py
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25010#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: danielquinn | Owner: nobody
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"5cc1f13d1586da62efbff3163f19c2bbcaea83ac" 5cc1f13d]:
{{{
#!CommitTicketReference repository=""
revision="5cc1f13d1586da62efbff3163f19c2bbcaea83ac"
[1.8.x] Fixed #25010 -- Documented APP_DIRS default in startproject's
settings.py
Backport of 4a6656488893b6a832726cade2d2c5aa04f85ae2 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25010#comment:5>