Show Commit Hashes

[bebehei]

I'm currently misusing html_last_updated_fmt for my whole project and set it for the whole project. (Source)

git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
html_last_updated_fmt = os.popen(git_cmd).read()

This shows the same date and commit on all pages.

---

While using this repository, the commit information is completely gone. As far as I can see in the code, it should be easily retrievable, since you're already working with commit hashes all the time.

I've replaced this for now with your repo. But the Revision is now missing.

https://github.com/mgeier/sphinx-last-updated-by-git/blob/d9037a358aaee37a6a6cc2ea1d939ed17eca6d94/src/sphinx_last_updated_by_git.py#L226-L227

Could you add there also a revision (the commit hash) into the html contex, too?

Popular Themes could pick this up then automatically:

https://github.com/readthedocs/sphinx_rtd_theme/blob/0da22b885be387b79f7552c92be00fd14d11228a/sphinx_rtd_theme/footer.html#L27-L43

[mgeier]

I'm not sure what's the use for a reader of showing the commit hash. Can you please elaborate?

Do you have a public link to your documentation showing a commit hash?

What I like to do instead, is creating a source link on each page (e.g. at the very bottom of https://insipid-sphinx-theme.readthedocs.io/en/0.4.2/configuration.html#confval-html_show_sourcelink). This links directly to the appropriate version of the source file on Github (other hosting services are of course also possible), which gives a reader direct access to the file history and the latest commit is immediately visible at the top of the Github page.

[Ashark]

I have exactly the same use case as OP described. Using git-cmd that makes a string in a date format that I like, and including the commit hash. And I run it with os.popen(git_cmd).read() to create the html_last_updated_fmt value.

Can you please make it controllable to define the --date and --pretty for the displayed date?

[mgeier]

I have exactly the same questions as to OP:

I'm not sure what's the use for a reader of showing the commit hash. Can you please elaborate?

Do you have a public link to your documentation showing a commit hash?

Can you please make it controllable to define the --date and --pretty for the displayed date?

I don't know what exactly you mean by that, can you please elaborate?

Would you like to create a PR?

[Ashark]

I'm not sure what's the use for a reader of showing the commit hash.

I want to see such thing to ensure I am seeing the correct version. For example, when generated locally. Or when it is published in a web site, I want to ensure that the documentation was builded and uploaded against the correct commit hash.

You can see the commit hash is even displayed for the sphinx own documentation: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

Can you please make it controllable to define the --date and --pretty for the displayed date?

I don't know what exactly you mean by that, can you please elaborate?

For example, I use this in my conf.py:

git_cmd = "git log --date=format:'%Y-%m-%d %H:%M:%S %z' --pretty='format:%ad, commit %h' -n1"
html_last_updated_fmt = os.popen(git_cmd).read()

This results in the following text in footer:

Last updated on 2024-03-29 04:51:40 +0300, commit 7479b0f.

When I use this extension:

extensions = [
...
    "sphinx_last_updated_by_git",
]

# Commented these out
# git_cmd = "git log --date=format:'%Y-%m-%d %H:%M:%S %z' --pretty='format:%ad, commit %h' -n1" 
# html_last_updated_fmt = os.popen(git_cmd).read()

I am getting in footer:

Last updated on Mar 24, 2024.

So, the extension worked (the date is changed to the modified, not to the last commit). But I would still want to use the original date format and also write the commit hash (with this extension it should be the commit hash of last page edit, not last commit). Is that possible?

In other words, I would like to get such string when using this extension:

Last updated on 2024-03-24 2024-03-29 04:51:40 +0300, commit 7479b0f.

Additionally, I also would like to keep the last commit hash. Is that possible? I mean, that the page footer for example would look like this:

Last page modification: 2024-03-24 23:23:40 +0300, commit 3bebf9cd.
Last documentation build: 2024-03-29 04:51:40 +0300, commit 7479b0f.

[mgeier]

I'm not sure what's the use for a reader of showing the commit hash.

I want to see such thing to ensure I am seeing the correct version. For example, when generated locally. Or when it is published in a web site, I want to ensure that the documentation was builded and uploaded against the correct commit hash.

This sounds like something you as a maintainer would like to know, it doesn't sound like that's of any use for your readers.

Also, this sounds like you are interested in the "published site version hash", not in the "hash when this individual page was last changed".

But anyway, you as a site maintainer can easily check both by looking at the "show source" link, e.g. at the bottom of this page: https://insipid-sphinx-theme.readthedocs.io/en/0.4.2/ The URL contains the hash of the built version (in this case 74e15da6) and when you click on it, you see the last change in the GitHub interface (in this case c2771ae).

I still don't see the need for displaying any of these hashes directly on the page.

You can see the commit hash is even displayed for the sphinx own documentation: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

This is not Sphinx's own documentation!

And even if it were, this alone wouldn't suffice to convince me, you should still make a case for why this would be useful for a reader.

But I would still want to use the original date format and also write the commit hash (with this extension it should be the commit hash of last page edit, not last commit). Is that possible?

No. As the name html_last_updated_fmt suggests, that's for specifying a date/time format for a given timestamp.

The commit hash would have to be provided as a separate Jinja variable.

Additionally, I also would like to keep the last commit hash. Is that possible? I mean, that the page footer for example would look like this:

Last page modification: 2024-03-24 23:23:40 +0300, commit 3bebf9cd.
Last documentation build: 2024-03-29 04:51:40 +0300, commit 7479b0f.

Again, what's the use for a reader to know the date of the "documentation build" if they already know the date of the "last page modification"?

BTW, it seems a bit overzealous to show the time of day. For most cases, the date should suffice. And if readers really want to know the time down to the second, they can always click on the source link.

[bebehei]

Again, what's the use for a reader to know the date of the "documentation build" if they already know the date of the "last page modification"?

In case the "maintainer" is the reader itself, isn't it a valid use case?

We're using this for our internal systems documentation and would like to see this for every page.

[mgeier]

In case the "maintainer" is the reader itself, isn't it a valid use case?

A single person can be both, but at any given moment they will lean towards one of the two. And only when they are in a maintainer mood, will they wonder about the Git hash.

And any use case is valid, there are just some use cases I personally am not particularly interested in.

We're using this for our internal systems documentation and would like to see this for every page.

If you'd like to see this, feel free to make a PR.

If it isn't too complicated and doesn't disturb too much (i.e. if it's disabled by default), I'm very much willing to review and eventually merge it.