Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
slafs opened this issue May 2, 2024 · 5 comments
Open

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

slafs opened this issue May 2, 2024 · 5 comments
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)

Comments

@slafs
Copy link

slafs commented May 2, 2024

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.
@slafs slafs added the T: documentation Improvements to the docs (e.g. new topic, correction, etc) label May 2, 2024
@JelleZijlstra
Copy link
Collaborator

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
Copy link
Author

slafs commented May 2, 2024

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
Copy link
Collaborator

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

@slafs
Copy link
Author

slafs commented May 2, 2024

@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
Copy link
Collaborator

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

@huonw huonw mentioned this issue Jun 13, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@slafs @JelleZijlstra