Unpin sphinx alternative

[mhvk]

Description

This pull request is an alternative to #14093 to unpin sphinx. It uses many commits from there that make references canonical, but instead of :noindex:, it replaces the astropy.units.function entry with astropy.units.function.core (which is where classes are actually defined) and uses the automodule directive for astropy.coordinates.builtin_frames so that the docstring and transformation graph are shown, but not all the classes.

Note that this includes also the strange annoyance that the numpy link is not working.

• Fixes DOC: Warnings about duplicate object description of astropy.coordinates.builtin_frames #11723
• Fixes DOC: Unpin max version of Sphinx when Sphinx 4.0.2 is out (and Jinja2) #11725
• Fixes Compatibility with Sphinx ≥ 4 #14115

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• 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 "When to rebase and squash commits".
• 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?
• Is a milestone set? Milestone must be set but astropy-bot check might be missing; do not let the green checkmark fool you.
• 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.

[mhvk]

New "Built-in Frame Classes" part of documentation at https://astropy--14140.org.readthedocs.build/en/14140/coordinates/index.html#module-astropy.coordinates.builtin_frames

[Cadair]

I think that the loss of the list of built in frame classes is unfortunate. I don't know what the best way to generate such a list is, but they are very easily lost in the full module API.

[mhvk]

The list is in the figure; ideally, that would be clickable. But I think we could fairly add the list as a table to the docstring. That would have the benefit that one doesn't get the various Base* frames in there as well.

[Cadair]

I think having an explicit list (which is clickable) is all I am after. Autogenerating that in the same way as the graph is 👍 from me.

[mhvk]

@Cadair - how about this: https://astropy--14140.org.readthedocs.build/en/14140/coordinates/index.html#module-astropy.coordinates.builtin_frames
(code in 5d8e440).

[Cadair]

Looks good! (Arguably better than the old one)! 🚀

[saimn]

Indeed, no need for :noindex: (astropy/sphinx-automodapi#150) finally but the current solution looks great. I like that the builtin_frames module no more appears in the docs.

[pllim]

Yay, thanks all!

[mhvk]

Indeed, thanks! I opened #14162 to remind us to put the numpy docs link back to stable.

[pllim]

I am trying to see how far I can push my luck here.

@meeseeksdev backport to v5.2.x

@meeseeksdev backport to v5.0.x

[pllim]

I'll see if I can backport #14206 to v5.0.x 🤪