id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
14633	Reorganize settings reference docs	Gabriel Hurley	Tim Graham	"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
}}}"	Cleanup/optimization	closed	Documentation	1.2	Normal	fixed		django@…	Accepted	1	0	0	0	0	0