Rename html_last_updated_time_zone to html_last_updated_use_utc

[AA-Turner]

Renamed per @mgeier's suggestion

xref #12907 (comment)

A

[mgeier]

Renamed per @mgeier's suggestion

For the record, I didn't suggest to rename it, I suggested to allow specifying arbitrary time zones, similar to what I'm doing in https://github.com/mgeier/sphinx-last-updated-by-git.

The renaming suggested by @AA-Turner is still an improvement, it makes the config value more consistent and less confusing!

BTW, while testing this, I found that the docs for html_last_updated_fmt are wrong: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_last_updated_fmt

They say "Default: '%b %d, %Y'", but the default is actually None:

sphinx/sphinx/builders/html/__init__.py

Line 1425 in 92aaf3d

app.add_config_value('html_last_updated_fmt', None, 'html', str)

[AA-Turner]

Fixed: 86531ab.

A

[AA-Turner]

I suggested to allow specifying arbitrary time zones

I'm open to this in the future, but I prefer avoiding the 'fun' of tzdata, zoneinfo, etc etc unless there is demonstrable demand -- as the docs note, this is only really useful for when the format used with html_last_updated_fmt contains the time rather than just the date.

A

[mgeier]

this is only really useful for when the format used with html_last_updated_fmt contains the time rather than just the date.

I find it strange when a site author chooses to display the time of day. I cannot imagine a situation where I as a reader want to know the exact second when the site was updated. To me a one-day resolution is plenty.

The reason why I implemented time-zone selection in my extension is the (hypothetical, never asked for) scenario where a company in New Zealand builds their docs on a server that's set to UTC (which e.g. Github Actions and RTD and probably many others are). When they make an edit in the morning, they get a different date than when they make an edit on the same day in the afternoon. So this (hypothetical) problem also appears if only the date is displayed.

But as I said, nobody has asked for that.

[AA-Turner]

We display the time of day on docs.python.org because we have regular rebuilds (~twice daily) instead of per-commit and it's useful to see how up-to-date it is. But a niche use-case.

A

[mgeier]

But a niche use-case.

More importantly, this seems like something that's only interesting to a site maintainer and it delivers no value to a user, right?

You are basically bragging how often you run your CI. That's fine if that's important to you.

If you want something more user-focused, you can try my extension https://github.com/mgeier/sphinx-last-updated-by-git.
You can use that one to brag how often you touch individual documentation pages, which is arguably a greater feat.

[AA-Turner]

I agree it's of more interest to site maintainers, yes. Though it started because CI ran ~every two days, so not something to brag about!

A