Opened 13 years ago

Closed 11 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 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

Attachments (2)

settings-001.diff (20.7 KB ) - added by Adam Vandenberg 13 years ago.
Initial patch, doesn't tackle STATICFILES yet.
settings-002.diff (21.9 KB ) - added by Adam Vandenberg 13 years ago.
More tweaks, includes markup app

Download all attachments as: .zip

Change History (17)

comment:1 by Gabriel Hurley, 13 years ago

Description: modified (diff)
Status: newassigned

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

comment:2 by Paul McMillan, 13 years ago

Triage Stage: UnreviewedAccepted

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

comment:3 by Adam Vandenberg, 13 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 Adam Vandenberg, 13 years ago

Attachment: settings-001.diff added

Initial patch, doesn't tackle STATICFILES yet.

by Adam Vandenberg, 13 years ago

Attachment: settings-002.diff added

More tweaks, includes markup app

in reply to:  3 comment:4 by Keryn Knight <keryn@…>, 13 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 Julien Phalip, 13 years ago

Severity: Normal
Type: Cleanup/optimization

comment:6 by Jacob, 12 years ago

milestone: 1.3

Milestone 1.3 deleted

comment:11 by Aymeric Augustin, 12 years ago

UI/UX: unset

Change UI/UX from NULL to False.

comment:12 by Aymeric Augustin, 12 years ago

Easy pickings: unset

Change Easy pickings from NULL to False.

comment:13 by Aymeric Augustin, 12 years ago

Owner: changed from Gabriel Hurley to Aymeric Augustin
Status: assignednew

comment:14 by Aymeric Augustin, 12 years ago

Owner: changed from Aymeric Augustin to Gabriel Hurley

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

comment:15 by jedie, 11 years ago

Cc: django@… added

comment:16 by Tim Graham, 11 years ago

Owner: changed from Gabriel Hurley to Tim Graham
Status: newassigned

comment:17 by Tim Graham, 11 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 Tim Graham, 11 years ago

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

comment:19 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: assignedclosed

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.

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