Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

Gosh, this is pretty awful. Given the strange build history, is it instead sphinx version dependent? Might it be better to just revert? (I.e., #16481)

Gosh, this is pretty awful.

Yeah, not great. Maybe more :noindex: on the other links from #15852 would actually fix this. I can investigate later.

Given the strange build history, is it instead sphinx version dependent?

Perhaps. Where in RTD can we see what version it was picking up?

Might it be better to just revert?

I hope not. What #15852 was doing was good. It would be a shame to revert that because of public API confusion.
In my many repos I have never suffered these issues with Sphinx nor RTD. There are some structural differences: PEP8 compliance and sphinx configuration.
Perhaps we can ameliorate the Sphinx issues by turning nitpicky off? Noticed by @eerovaher in #15852 (comment)

My suggestion would be to merge this PR then figure out how to revert THIS PR by either :noindex: additions or nitpicky settings.

#15852 removed link targets in our documentation (by adding the :noindex: instructions), but the documentation build succeeded in the pull request because it could find the link targets in the latest build of main. Likewise, the documentation build for 642fbc9 could still look up the link targets from the previous build, so it wasn't until the build for 642fbc9 had finished that the link targets became inaccessible. Similar problems occurred twice in December (#15698 and #15715). I don't fully understand every detail that contributes to the problem, but it apparently it has something to do with

The fix attempted here is not good because the documentation is now lacking links that were there before (compare the documentation for this pull request with the documentation for 6.1.0).

@nstarman might have identified the correct fix in #16473, but I don't expect that to be applied quickly, so in the short term we will have to merge #16481.

👎 to disable nitpicky. It has been useful in the past to catch real problems. Disabling it would be throwing out baby with the bath water.

Where in RTD can we see what version it was picking up?

You have to click on "raw log" link on the build job page to see everything.