Opened 7 years ago

Last modified 5 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
}}

Change History (0)

Note: See TracTickets for help on using tickets.
Back to Top