Documentation: templates are searched as a app sub-dir

[bnomis@…]

Besides the TEMPLATES_DIR variable Django also searches for templates in app/templates This used to be clear from the documentation but since MR it is no longer explicitly stated. I think this is a good thing to have and adheres to the DRY principle - since in this way we can contain all the files for an app in the app directory and do not have to specify both the app and the location of the app's templates in the settings.py file (unless of course we want to override the apps default templates).

[James Bennett]

This is dependent on the TEMPLATE_LOADERS setting, I believe.

[Malcolm Tredinnick <malcolm@…>]

This is documented in templates_python.txt (online at ​http://www.djangoproject.com/documentation/templates_python/#loader-types ). I think the text there is reasonably clear about when it searches in an app directory and gives examples.

But if you did not find this, it means we are not being clear enough with the location. Do you have a suggestion for where we could put this section to make it clearer (without being right up front, since it's not the most important thing in the whole world about the template system)? Also, do you find the text clear enough in that section, or any suggestions to improve it?

[bnomis@…]

Yes it is documented but the first thing on the page here ​http://www.djangoproject.com/documentation/templates_python/#the-template-dirs-setting makes it sound like there is only one way of specifying the dirs.

I suggest changing the intro text to something like the following:

"
Loading templates

Generally, you'll store templates in files on your filesystem rather than using the low-level Template API yourself. Save templates in a directory specified as a template directory. Django searches for template directories in a number of places:

• the templates directory of the applications specified in the INSTALLED_APPS setting
• directories specified in the TEMPLATE_DIRS setting

"

I think the section about searching in the app/templates directory should come first since this is where most application developers will be putting their templates. At the moment it just reads wrong to me.

[Adrian Holovaty]

(In [3061]) Fixed #1870 -- Clarified (hopefully) the TEMPLATE_DIRS section of docs/templates_python.txt