Opened 14 years ago
Last modified 12 years ago
#14633 closed
Reorganize settings reference docs — at Initial Version
Reported by: | Gabriel Hurley | Owned by: | Gabriel Hurley |
---|---|---|---|
Component: | Documentation | Version: | 1.2 |
Severity: | Normal | Keywords: | |
Cc: | django@… | Triage Stage: | Accepted |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
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 }}