Summary
Changelog entry anchors change per each release, as they are numbered sequentially. The following link is the anchor for 7.0.0 (2025-09-09), but won't be the same for the next release https://pytest-cov.readthedocs.io/en/latest/changelog.html#id1
This is a known bug in Sphinx, but there hasn't been any activity to fix it. sphinx-doc/sphinx#8709
Right now, this makes linking to a specific release sort of hard to do.
Solutions
I've come up with several options for a solution, all of which I'm willing to implement myself.
Option A: Add a v or other letter before each release header.
Put a v before each release header allows sphinx to properly create a fragment for the release. The example above would have a fragment of #v7-0-0-2025-09-09
Option B: A plugin and custom directive
Pip implemented a workaround in a custom plugin to add a ref for each release, so they wouldn't need to manually fix it on each pre-existing release.
https://github.com/pypa/pip/blob/2b8b99522f2fc686ede57b0392cf2e3a50e27284/docs/pip_sphinxext.py#L48-L70
Option C: manual ..ref headers
Instead of writing a custom plugin to fix the refs of each line, it is possible to implement a ref for each line one time, and simply add a ref in the future.
Option D: Do nothing, wait for an upstream fix
This might be the way to go, since I'm working on seeing if I can fix this in Sphinx/docutils.
Summary
Changelog entry anchors change per each release, as they are numbered sequentially. The following link is the anchor for 7.0.0 (2025-09-09), but won't be the same for the next release https://pytest-cov.readthedocs.io/en/latest/changelog.html#id1
This is a known bug in Sphinx, but there hasn't been any activity to fix it. sphinx-doc/sphinx#8709
Right now, this makes linking to a specific release sort of hard to do.
Solutions
I've come up with several options for a solution, all of which I'm willing to implement myself.
Option A: Add a
vor other letter before each release header.Put a
vbefore each release header allows sphinx to properly create a fragment for the release. The example above would have a fragment of#v7-0-0-2025-09-09Option B: A plugin and custom directive
Pip implemented a workaround in a custom plugin to add a ref for each release, so they wouldn't need to manually fix it on each pre-existing release.
https://github.com/pypa/pip/blob/2b8b99522f2fc686ede57b0392cf2e3a50e27284/docs/pip_sphinxext.py#L48-L70
Option C: manual ..ref headers
Instead of writing a custom plugin to fix the refs of each line, it is possible to implement a ref for each line one time, and simply add a ref in the future.
Option D: Do nothing, wait for an upstream fix
This might be the way to go, since I'm working on seeing if I can fix this in Sphinx/docutils.