Creating this issue to summarize the situation with Sphinx 4, and gather the pieces of information from the various issues/PRs.

So we are pinning Sphinx<4 since May, 2021 (#11724, #11725), because of some duplicate object description warnings with coordinates.builtin_frames and units.function.logarithmic, e.g.:

astropy/coordinates/builtin_frames/galactic.py:docstring of astropy.coordinates.builtin_frames.galactic.Galactic:1:
WARNING: duplicate object description of astropy.coordinates.builtin_frames.galactic.Galactic,
other instance in api/astropy.coordinates.Galactic, use :noindex: for one of them

(Note latest version of Sphinx is 5.3.0)

I tried various solutions:

• Fix warnings with Sphinx>4 #12270, didn't work
• Fix Sphinx>4 warnings with units and coordinates #13048, works but by removing the problematic sub-packages from the API docs.
• Unpin Sphinx #14093, using :noindex: for these sub-packages, which works but creates new reference target not found warnings when (I think) there are references to functions from these sub-packages...

The reasons for these warnings are described here : sphinx-doc/sphinx#10348 (comment). This is a long comment so I will not copy/paste it here, but it gives a clear explanation of the issue (and possible solutions, except :noindex: doesn't really work).
So if we want to unpin Sphinx (and we should rather not wait too long or other incompatibilities may arise with time), we should find a different solution to document the API for such cases. Maybe with some Sphinx directives manually ?

cc coordinates and units maintainers, @adrn @eteq @eerovaher @mhvk @nstarman