Docs could be improved for DATETIME_FORMAT?

I’d like to raise the question whether the docs for the DATETIME_FORMAT should be improved.

Quoting directly from Settings | Django documentation | Django

The default formatting to use for displaying datetime fields in any part of the system. Note that the locale-dictated format has higher precedence and will be applied instead. See allowed date format strings.

If the locale-dictated format has a “higher precedence”, how is the DATETIME_FORMAT setting any kind of “default”? (I guess it’s a default if the locale doesn’t define a format?)
With the removal of the L10N setting, should this be changed/reworded?

I also remember finding this confusing when doing some locale work months ago. I cannot recall the details of what I figured out though. A documentation improvement would be great, if you’d like to propose it.

Floating a couple ideas:


The formatting used for displaying datetime fields when not defined in the locale format. See allowed date format strings.


The default formatting used for datetime fields is usually defined in the locale format file. This setting defines a default when not defined in the locale format file.


I’m trying to keep this in the same general length as the original. I’d assume there’s no desire or intent to significantly expand the scope of the docs for this setting.

2 Likes

I think the first one sounds good to me!

I think this PR and specifically this comment on the settings is related to this discussion :thinking:
I also think the ticket associated for this PR can be used for this change: #35306 (Improve documentation for the various date format settings) – Django (djangoproject.com)

Feel free to open a PR Refs #35306 -- Clarified docs for DATETIME_FORMAT. (or something better) with your suggested updates :+1:

2 Likes

Thanks @sarahboyce , I’m really enjoying how you’re linking random forum threads back to existing tickets.

1 Like