#14633 - organization of settings docs

[Tim Graham]

I'd appreciate feedback on #14633 - "Organize settings reference docs". So far I've broken out the settings for each contrib app into their own sections. The one comment on the pull request suggests further breaking up the settings listed in the "Core settings" section, e.g. logging, caches, globalization (i18n/l10n), email, file uploads/media, storages, and security. I don't feel strongly about this proposal: it could be useful, but it could also be ambiguous as to which section a particular settings belongs in.

The pull request also suggests organizing the default settings.py in a similar fashion.  While it may be outside of the scope of this ticket, it could be worthwhile to discuss that suggestion as well.

[Sam Lai]

Looks good. Adds a bit more structure for browsing but doesn't
significantly change how the page is used, which is probably through
CTRL-F.

As mentioned by others in the issue, the distinction current and
deprecated settings seems very arbitrary. I think it'll be better to
sort the deprecated settings like any other setting, but include a
better visual distinction to indicate that they're deprecated (at
least bold the word deprecated I think). When someone's looking for a
setting, they're not thinking about whether or not a setting is
deprecated; they're probably looking for what it means and how it can
be configured.

> --
> You received this message because you are subscribed to the Google Groups
> "Django developers" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/django-developers/-/Uku6Vo8oCvIJ.
> To post to this group, send email to django-d...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-develop...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/django-developers?hl=en.

[Tim Graham]

Agreed, I'm +1 to keeping deprecated settings inline rather than moving them to their own section, but I'd defer to whoever made the original decision.

[ptone]

Looks good overall Tim - I do think that the primary reference should be kept alphabetical within core - this is most useful when you have a setting you need to look up.  But I do think that a 'by-topic' cross reference index could also be very useful for discovering or learning about all settings.  Such an index could be at the bottom of the page, and include the topics suggested, as well as the deprecated settings - settings that apply to more than one topic could be duplicated in such an index, and deprecated settings could be duplicated under a topic, and under a "deprecated" heading in such an index. This is a case where more organization is only good, and there is no reason we have to choose an either or.

-Preston

[Tim Graham]

Thanks for the suggestion, I've added a topical index to the pull request.