Fixup references to point to pertinent version rather than current

[ktbarrett]

I have been busy removing and moving things around in one of the projects I work on and notice that I end up with dead references in release notes for old versions. IMO these references should point to the RTD page for the version the release notes are for rather than the current one.

I know this requires making a bunch of assumptions, but I'm wondering if anyone else has been annoyed by this, if there is a way to do this in towncrier already, if there is an extension, if there is interest in implementing this in towncrier, etc. etc.

For example:

This newsfragment is created during the v1.3 development cycle.

Added ``verbose`` argument to :func:`do_stuff`.

Towncrier is used to generate the release notes and prepend them to the historical list of release notes.

Later in v2.0 do_stuff is removed or moved. The link in the newsfrag above, which is inserted into the release notes, is now broken.

There are a couple ways to deal with this:

1. If moved, you can manually update the ref, but this potentially changes the fully qualified name in an older version which won't be correct if you have the older version checked out.
2. If removed, you can just create unlinked names: Added ``verbose`` argument to :func:`my_pack.do_stuff` -> Added ``verbose`` argument to ``my_pack.do_stuff``

Either "solution" are less than ideal. IMO Towncrier could fixup the references (:func:`my_pack.do_stuff` ) to point to the appropriate documentation in the version you are using towncrier to generate. So if you are generating release notes for v1.3 that previously mentioned reference would be fixed up to :ref:`my_pack.do_stuff() <https://docs.myproject.org/en/v1.3/index.rst#my_pack.do_stuff>` so the reference will never die and if clicked will take you to the documentation for that entity as it was in that version.

[adiroiban]

Hi Kaleb.

I am not sure what is reported here.

Can you please describe (with an example that can be reproduced by others) the current towncrier behaviour versus the expected behaviour ?

Thanks

[ktbarrett]

I updated the OP.

[adiroiban]

towncrier is just a simple tool to generate a text file from a set of other text files.

towncrier is not parsing or managing RST or Markdown content.

From you description, it looks like you are looking after some sort of extension for Sphinx.

If you think that this needs to be fixed by towncrier my suggestion is to send a PR with your preferred fix.

As long as the PR has documentation, automated tests and is not breaking backward compatiblity, we can have this fixed.