Opened 14 years ago
Closed 12 years ago
#14633 closed Cleanup/optimization (fixed)
Reorganize settings reference docs
Reported by: | Gabriel Hurley | Owned by: | Tim Graham |
---|---|---|---|
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 (last modified by )
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
Attachments (2)
Change History (17)
comment:1 by , 14 years ago
Description: | modified (diff) |
---|---|
Status: | new → assigned |
comment:2 by , 14 years ago
Triage Stage: | Unreviewed → Accepted |
---|
I'm in favor of Option 1 including the app name. It's how I would go looking for those settings.
follow-up: 4 comment:3 by , 14 years ago
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?
by , 14 years ago
Attachment: | settings-001.diff added |
---|
Initial patch, doesn't tackle STATICFILES yet.
comment:4 by , 14 years ago
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.)
comment:5 by , 13 years ago
Severity: | → Normal |
---|---|
Type: | → Cleanup/optimization |
comment:13 by , 13 years ago
Owner: | changed from | to
---|---|
Status: | assigned → new |
comment:14 by , 13 years ago
Owner: | changed from | to
---|
I'm not going to have time for this soon, I'm returning the ticket to the previous owner.
comment:15 by , 12 years ago
Cc: | added |
---|
comment:16 by , 12 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:17 by , 12 years ago
Has patch: | set |
---|
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.
comment:18 by , 12 years ago
Based on mailing list feedback, I've added a topical index for the core settings.
comment:19 by , 12 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
Added a missing "}" to the code formatting. ::sigh::