pip: Changelog/release notes sections do not have stable anchors
Description
The section headers in the changelog/release notes do not have proper stable anchor IDs. Instead, they have generic numbered IDs like id123. This makes it impossible to link to a specific section of the changelog in a way that will continue working in the future: for example the section for version 20.0 has anchor ID id6 in the current stable version of the docs, and anchor ID id35 in the current latest version. These IDs seem to be assigned sequentially from the start of the file, so they are guaranteed to change when a new version section is added.
Expected behavior Each version section (and preferrably also each subsection) should have a unique anchor ID that does not change when a new pip release is added to the changelog.
(I’m violating the issue template a bit here - this is a documentation issue, so pip version, OS, etc. don’t really apply.)
About this issue
- Original URL
- State: closed
- Created 4 years ago
- Reactions: 5
- Comments: 19 (12 by maintainers)
The solution doesn’t belong to Sphinx IMO, since it is actually working around a Towncrier restriction with Sphinx, and Sphinx users in general does not need that patch at all. I’ve commented under the Sphinx issue to provide a general Sphinx solution to the issue.
I wonder if it is possible to resolve this in Towncrier by adding an explicit ref derivitive to each release section.
@wimglenn The problem to this issue is that the changelog page is machine-generated. The section you are referring is written by a human, and likely broken by a botched merge conflict resolution. Feel free to submit a pull request to amend it. Specifically, this line should be moved to right above the relevent secion.