pytest-dev
Changelog entry anchors are numbered sequentially and change upon release
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. https://github.com/sphinx-doc/sphinx/issues/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.
How would the manual refs look like (option C)? I'm inclined to have either A or C - don't really want to have yet another thing to maintain.
Taken from the sphinx issue:
A simpler workaround would be to use headings starting with an ASCII letter (
release 25.1.0or similar) or to provide explicit targets like.. _release 25.1.0: 25.1.0 =====
I think prefixing everything with v is the easiest and least noisy. I'm writing this changelog by hand after all. You can do it if you want, or I'll do it before next release :-)