search

pypa / twine

Utilities for interacting with PyPI
https://twine.readthedocs.io/
Apache License 2.0
1.61k stars 308 forks source link

Add explicit link targets to releases in changelog #723

Closed bhrutledge closed 3 years ago

bhrutledge commented 3 years ago

As a result of https://github.com/pypa/twine/issues/683#issuecomment-750902976, I thought one way to make the release tags more useful would be to have a link to the changelog, e.g.

git tag -m "https://twine.readthedocs.io/en/latest/changelog.html#3.3.0" 3.3.0

However, the default towncrier template doesn't generate explicit targets, so right now the link to 3.3.0 is https://twine.readthedocs.io/en/latest/changelog.html#id1. Similar, the features for 3.3.0 is referenced by #features, but for 3.2.0 it's #id14.

Maybe this could/should be proposed as a change to towncrier, but thought I'd see if there was any appetite for it here.

sigmavirus24 commented 3 years ago

Eh, it could be helpful but I'm not sure if it is the best approach. I get that it'll display on the releases page, but I worry about readthedocs changing their domain again or switching to another docs service. Not a big deal, but this could be very useful to have in towncrier regardless.

bhrutledge commented 3 years ago

Regardless of the git tag, I still think it would be handy to have direct links to releases in the rendered changelog. Some towncrier-based projects already have that:

They all have custom towncrier templates, but they don't seem to include explicit targets. That makes me wonder if there's a configuration that enables this behavior.

sigmavirus24 commented 3 years ago

Do you mean in the side navigation bar? That's handled by sphinx iirc with :toctree: options I think?

bhrutledge commented 3 years ago

I mean URLs like this, which jump to directly to the changelog for a release: https://virtualenv.pypa.io/en/latest/changelog.html#v20-0-23-2020-06-12

One observation is that those examples all have headings that begin with a letter, whereas Twine's start with a number. I wonder if that's it, since the IIRC id has to start with a letter. Maybe this could be resolved by using the title_format option to prepend a v...

jaraco commented 3 years ago

Right - it's a Sphinx or Restructured text issue. It can't generate anchors for headings that begin with numbers. That's why I switched to v prefixes in skeleton projects.