TEMPLATES settings documentation is confusing about APP_DIRS

[Daniel Quinn]

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.

[Moritz Sichert]

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.

[Tim Graham]

Daniel, I've attached a patch. Let us know if you have any other suggestions besides that.

[Daniel Quinn]

I read your patch and I literally just said: "Oh!" This makes *so* much more sense now. Yes, I think this is probably sufficient.

[Tim Graham <timograham@…>]

In 4a66564:

Fixed #25010 -- Documented APP_DIRS default in startproject's settings.py

[Tim Graham <timograham@…>]

In 5cc1f13d:

[1.8.x] Fixed #25010 -- Documented APP_DIRS default in startproject's settings.py

Backport of 4a6656488893b6a832726cade2d2c5aa04f85ae2 from master