One of my pet peeves are projects without easily accessible changelogs (secondary pet peeve: changelogs without dates). Currently, I’m moving most auxiliary docs to Markdown, because that’s clearly what GitHub and related tooling wants me to. But I don’t want to compromise on my own pet peeve.
What I like is to have a prominent link at the top of my project’s documentation pages that link to the relevant changelog (see e.g. for structlog). Now that the changelog is not part of the Sphinx documentation anymore, I just want to link to the CHANGELOG.md file on GitHub at a certain git commit tag.
It’s a bit more involved than I expected, because Sphinx doesn’t allow for templating in links. But it’s doable with a little trick.
Put the following into your Sphinx’s conf.py (with adjusted project names and URLs, of course):
from importlib import metadata
release = metadata.version("argon2-cffi")
rst_epilog = f"""
.. |changelog| replace:: What’s new?
.. _changelog: https://github.com/hynek/argon2-cffi/blob/{release}/CHANGELOG.md
"""
Now, whenever you put |changelog|_ in your Sphinx .rst files, it gets rendered as something like this:
<a href="https://github.com/hynek/argon2-cffi/blob/21.2.0/CHANGELOG.md">
What’s new?
</a>
