search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.59k stars 2.12k forks source link

Allow using GMT in the HTML last updated format #12907

Closed AA-Turner closed 1 month ago

AA-Turner commented 1 month ago

Feature or Bugfix

Purpose

Add html_last_updated_time_zone to allow using GMT (universal time) instead of local time for the date-time supplied to html_last_updated_fmt.

Detail

This is useful when html_last_updated_fmt includes hours or minutes, and when working on a project that spans time zones. For example, the Python project (at time of writing) overwrites html_last_updated_fmt with a static time as local time is unhelpful.

A

mgeier commented 1 month ago

Wouldn't it be more useful to be able to specify an arbitrary time zone instead of only having GMT as a choice?

This is how I did it in my sphinx_last_updated_by_git extension: https://github.com/mgeier/sphinx-last-updated-by-git/blob/7d226ef95ff2e19caaddc5018fb86f1bbf304232/src/sphinx_last_updated_by_git.py#L258-L263

Also, I'm not sure if "GMT" is the right term. Shouldn't it be "UTC"?

AA-Turner commented 1 month ago

Perhaps, but I'm not particularly fond of adding more options. By default I think continuing to target the local timezone is the right choice.

The option here is to use a standard time, for which GMT/UTC/Universal time seemed most appropriate. To my knowledge there haven't been any requests to configure timezones?

A

mgeier commented 1 month ago

To my knowledge there haven't been any requests to configure timezones?

No, I didn't get any requests.

I just find it strange to provide a "timezone" configuration and then only allow 'local' | 'GMT'.

When I hear "timezone", I'm expecting to be able to select any time zone I want, not only one.

AA-Turner commented 1 month ago

Perhaps we could rename? use_local_timezone / use_system_timezone / use_gmt / ??

A

mgeier commented 1 month ago

Yes, those names would be more consistent.

It should probably be prefixed with html_last_updated_, though.

Who actually requested this? Maybe they should chime in?

I would also suggest again to re-think whether "GMT" is the right name.

I just tried it and when I'm specifying:

html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %Z'

... then I'm getting this:

Last updated on 2024-10-03 16:29:34 UTC.

So maybe using "UTC" would be more appropriate?

If you are interested, you can also try my extension https://github.com/mgeier/sphinx-last-updated-by-git, where I'm getting this mapping: