Repository navigation
Changelog doesn't contain any intersphinx links #10286
Description
I was looking down the changelog here: https://docs.astropy.org/en/latest/changelog.html#unreleased, and thought it was a shame that all of the links to new functions/methods/classes didn't have intersphinx links. It would be nice if they were properly linked so if someone sees something they want to take a further look at, they can just click through to the API documentation.
EDIT: Blocked by #10334
Activity
bsipocz commentedon May 3, 2020
This is intentional to avoid issues with changing docs references and disappearing API links.
bsipocz commentedon May 3, 2020
(It was a constant source of pain of breaking links, if needed I can dig up old references for PRs and issues).
dstansby commentedon May 3, 2020
Could the links not be removed when what they point to disappears? Using the above argument, presumably intersphinx links would never be included anywhere because they might disappear in the future.
bsipocz commentedon May 3, 2020
The difference, as I see, is that the CHANGELOG is a static document to snapshot a release, while docs and docstrings are living ones.
pllim commentedon May 4, 2020
The decision to not use "live links" in change log was made long ago. I don't see the reason to revert now?
dstansby commentedon May 4, 2020
Fair enough, although I think this really does harm discoverability of new features - currently I have to manually do an individual search in the search box for everything I want to know more about, whereas with links I could quickly open a bunch of pages in new tabs. Also, I would have thought new features aren't going to disappear or have their API changed all the time too, so maybe stale links were a bigger issue when the project was less API stable?
astropy-bot commentedon May 12, 2020
Hi humans 👋 - this issue was labeled as Close? approximately 7 days ago. If you think this issue should not be closed, a maintainer should remove the Close? label - otherwise, I will close this issue in a month.
If you believe I commented on this issue incorrectly, please report this here
saimn commentedon May 15, 2020
I think it would be great to have links in the changelog. They shouldn't be used for some specific cases, like deprecation as the functions will disappear later, but other than that it would help a lot to discover new features.
pllim commentedon May 15, 2020
I think we should table this until #10334 is resolved.
Update README for sub-packages and intersphinx
Update README for sub-packages and intersphinx
Update README for sub-packages and intersphinx
Update README for sub-packages and intersphinx
Update README for sub-packages and intersphinx
embray commentedon Apr 22, 2021
Perhaps at least for the most recent release (or even more, any releases for which the docs are available on RTD) it could render the appropriate API links.
bsipocz commentedon Apr 22, 2021
And then remove those API links afterwards? We had those in the past, and I remember the pain of fixing them...
dstansby commentedon Apr 22, 2021
Is it really too much hassle to remove links in a PR that's removing API? I also want to re-iterate my previous point from above:
Cadair commentedon Apr 22, 2021
Can't we just ignore broken links in the rendered changelog? Most links working is better than no links working.
embray commentedon Apr 26, 2021
I was thinking this could be done automatically by towncrier but I don't know how easy that would be. It might be something possible to do within the template used by towncrier.
Update README for sub-packages and intersphinx
pllim commentedon May 8, 2026
I still don't think this is worth pursuing. I feel like links will be broken again a few years from now and then we get bitten again. This will just spin us around in circles.