Opened 5 years ago

Closed 2 years ago

#14633 closed Cleanup/optimization (fixed)

Reorganize settings reference docs

Reported by: gabrielhurley Owned by: timo
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 gabrielhurley)

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 adamv 5 years ago.
Initial patch, doesn't tackle STATICFILES yet.
settings-002.diff (21.9 KB) - added by adamv 5 years ago.
More tweaks, includes markup app

Download all attachments as: .zip

Change History (17)

comment:1 Changed 5 years ago by gabrielhurley

  • Description modified (diff)
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Status changed from new to assigned

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

comment:2 Changed 5 years ago by PaulM

  • Triage Stage changed from Unreviewed to Accepted

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

comment:3 follow-up: Changed 5 years ago by 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?

Changed 5 years ago by adamv

Initial patch, doesn't tackle STATICFILES yet.

Changed 5 years ago by adamv

More tweaks, includes markup app

comment:4 in reply to: ↑ 3 Changed 5 years ago by Keryn Knight <keryn@…>

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 Changed 4 years ago by julien

  • Severity set to Normal
  • Type set to Cleanup/optimization

comment:6 Changed 4 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

comment:11 Changed 3 years ago by aaugustin

  • UI/UX unset

Change UI/UX from NULL to False.

comment:12 Changed 3 years ago by aaugustin

  • Easy pickings unset

Change Easy pickings from NULL to False.

comment:13 Changed 3 years ago by aaugustin

  • Owner changed from gabrielhurley to aaugustin
  • Status changed from assigned to new

comment:14 Changed 3 years ago by aaugustin

  • Owner changed from aaugustin to gabrielhurley

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

comment:15 Changed 3 years ago by jedie

  • Cc django@… added

comment:16 Changed 2 years ago by timo

  • Owner changed from gabrielhurley to timo
  • Status changed from new to assigned

comment:17 Changed 2 years ago by timo

  • 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 Changed 2 years ago by timo

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

comment:19 Changed 2 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

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