Reorganize settings reference docs

[Gabriel Hurley]

Currently, docs/ref/settings contains an alphabetical list of most of the settings contained in conf/global_settings.py, including those for some contrib apps (auth, sessions, ...). However, settings for a handful of contrib apps (comments, staticfiles, ...) live in their respective /docs/ref/contrib/[app] documentation files.

AFAICS the settings reference ought to encompass all of the settings contained in the global_settings module if it is going to be a "full list of all available settings" as it claims.

We don't want to overload that document, though, and maintaining some sort of logical grouping is necessary. jezdez and I discussed this issue briefly on IRC, and decided it might be helpful to create a section within docs/ref/settings specifically for contrib app settings.

The ultimate structure could look like this:

Settings
 |-- Available settings
    |-- Core settings
    |-- Contrib settings
        |-- (App name?)
 |-- Deprecated settings

or more simply:

Settings
 |-- Core settings
 |-- Contrib settings
     |-- (App name?)
 |-- Deprecated settings

The contrib app docs could then point to the appropriate section of the settings reference.

As another alternative structure, the settings reference could be grouped according to the organization of global_settings.py (shown here in alphabetical order):

Settings
 |-- Authentication
 |-- Cache
 |-- Comments
 |-- Core
 |-- CSRF
 |-- Fixtures
 |-- Logging
 |-- Messages
 |-- Middleware
 |-- Sessions
 |-- Staticfiles
 |-- Testing

[Gabriel Hurley]

Added a missing "}" to the code formatting. ::sigh::

[Paul McMillan]

I'm in favor of Option 1 including the app name. It's how I would go looking for those settings.

[Adam Vandenberg]

Should the settings in the individual contrib app docs then be removed and replaced with a link to the relevant section of the master settings list? Or should there be some amount of textual duplication?

[Adam Vandenberg]

Initial patch, doesn't tackle STATICFILES yet.

[Adam Vandenberg]

More tweaks, includes markup app

[Keryn Knight <keryn@…>]

Replying to adamv:

Should the settings in the individual contrib app docs then be removed and replaced with a link to the relevant section of the master settings list? Or should there be some amount of textual duplication?

I would be in favour of providing obvious links from a contrib app's documentation to the relevant section in the master template list, for the simple reason that duplication means more maintenance, and more room for future changes to be missed, with no obvious benefit.
Most people will either be browsing online, or using a locally built copy, so hopping to a different (logically separate) section dealing specifically with configuration shouldn't be an onerous task to ask of the end user (who arguably ultimately benefits from the lack of duplication, and is trained via user-experience into going to one specific section, regardless of the app in question)

Of the proposed structures in the ticket, I think the first makes an unnecessary distinction between 'Available settings' and 'Deprecated settings' which the others do not - Deprecated settings are still available, until the release in which they are not (at which point, presumably, they are dropped from the documentation and added to the backwards incompatible change list.)

[Jacob]

Milestone 1.3 deleted

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[Aymeric Augustin]

I'm not going to have time for this soon, I'm returning the ticket to the previous owner.

[Tim Graham]

pull request: ​https://github.com/django/django/pull/620
rendered preview: ​http://techytim.com/django/14633/ref/settings.html

While not technically a contrib app (though the docs live at /ref/contrib/csrf/), I considered putting the CSRF settings in their own section, but didn't feel strongly about it either way.

I also didn't touch GeoDjango settings as they seem fine within the GeoDjango docs.

[Tim Graham]

Based on mailing list feedback, I've added a topical index for the core settings.

[Tim Graham <timograham@…>]

In ba50d3e05bc9a33aef495a5fbca239afe52237b3:

Fixed #14633 - Organized settings reference docs and added a topical index.

Thanks Gabriel Hurley for the original idea
and adamv for the draft patch.