Is there any way to have a permalink for a specific version in the changelog doc?

[slafs]

Is this related to a problem? Please describe.

It would be nice if one could copy-paste links to the https://black.readthedocs.io/en/stable/change_log.html doc with anchors to specific versions.

ATM the page seems to put idX anchors on each header,
where X is an incrementing number.

This means that over time the underlying content changes (with each release)
and there seems to be no way to point people to a specific section (version) of that doc
regardless of what the most recent release is.

Describe the solution you'd like

Switch from #id1, #id2 etc. header anchors
to something more permanent e.g. #v24.4.2,
which would point to a changelog section for the 24.4.2 version.

[JelleZijlstra]

PR welcome. We don't do anything special for this file, so changing this would require some investigation into how our docs stack generates headers.

[slafs]

Took a look, but not sure what's the issue here.

Funny enough, only the changelog page seem to have this problem.
Others seem fine e.g. https://black.readthedocs.io/en/latest/getting_started.html#installation

Also, if I add v in front of the version number in CHANGES.md e.g. ## v24.4.2,
then the anchor is correct - #v24-4-2.

If I add text at the end e.g. ## 24.4.2 - this is weird then the anchor is #this-is-weird.

Maybe there's some leading number stripping going on in Sphinx? 🤔
Because this doesn't seem like a MyST parser issue.
🤷

Seems like pip had a similar problem, but they have a special plugin for including the changelog even 😅 - https://github.com/pypa/pip/blob/3f3bc6000c512abfd518f6b200383451d020f7d8/docs/pip_sphinxext.py#L48-L70.

[JelleZijlstra]

I'd be open to changing the headers to something like "Version 24.4.2".

[slafs]

@JelleZijlstra cool. Can you point me to a place where the "Unreleased" section of CHANGES.md gets turned into the version number after the release?

[JelleZijlstra]

https://github.com/psf/black/blob/main/scripts/release.py