Add explicit link targets to releases in changelog

[bhrutledge]

As a result of #683 (comment), 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]

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]

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:

• https://virtualenv.pypa.io/en/latest/changelog.html
• https://setuptools.readthedocs.io/en/latest/history.html
• https://dateutil.readthedocs.io/en/latest/changelog.html
• https://tox.readthedocs.io/en/latest/changelog.html

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]

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

[bhrutledge]

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]

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.