[Django] #32521: Possible documentation error re. template directories
Django
-----------------------------------------+------------------------
Reporter: Mike Slinn | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 3.1
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+------------------------
[https://docs.djangoproject.com/en/3.1/howto/overriding-templates
/#overriding-from-an-app-s-template-directory The docs] say "Since you’re
overriding templates located outside of one of your project’s apps, it’s
more common to **use the first method** and put template overrides in a
project’s templates folder."
It is unclear what "the first method" might be. Earlier in the page there
was no mention of an enumeration of options.
I believe I know what the page is trying to communicate, that there are
two places to put templates:
1) Per app (template subdirectory within each app directory)
2) Per project (top-level /templates directory)
I believe that the first place shown above is "the first method". It would
be less confusing if this was spelled out better. The rest of the page
continues the confusion. Apparently per-app templates are preferred, but
there is not a single example of this, nor a directory layout image, and
instead all the detail goes to the per-project option.
Even the section entitled [https://docs.djangoproject.com/en/3.1/howto
/overriding-templates/#overriding-from-an-app-s-template-directory
Overriding from an app’s template directory] does not discuss per-app
templates, and again shows a per-project template directory.
A newbie like me is left scratching his head.
--
Ticket URL: <https://code.djangoproject.com/ticket/32521>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Mike Slinn | Owner: nobody
Cleanup/optimization |
Component: Documentation | Version: 3.1
Severity: Normal | Resolution: invalid
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 Mariusz Felisiak):
* status: new => closed
* type: Uncategorized => Cleanup/optimization
* resolution: => invalid
Comment:
This page describes how to override templates in three ways:
- ''"Overriding from the project’s templates directory"''
- ''"Overriding from an app’s template directory"''
- ''"Extending an overridden template"''
> It is unclear what "the first method" might be. Earlier in the page
there was no mention of an enumeration of options.
TBH I cannot imagine how we could be clearer. ''"... it’s more common to
use the first method and put template overrides in a project’s templates
folder."'' so the first method is to ''"...put template overrides in a
project’s templates folder..."'' i.e. the first way described on this
page.
> Apparently per-app templates are preferred, but there is not a single
example of this, nor a directory layout image, and instead all the detail
goes to the per-project option.
That's not true, this is described in the
[https://docs.djangoproject.com/en/3.1/howto/overriding-templates
/#overriding-from-an-app-s-template-directory "Overriding from an app’s
template directory"] section, with an example of directory structure:
> ''"If you want to put the template overrides in **an app** called
**myapp** and the templates to override are named blog/list.html and
blog/post.html, then your directory structure will look like:"''
--
Ticket URL: <https://code.djangoproject.com/ticket/32521#comment:1>