Repository navigation
Compatibility with Sphinx ≥ 4 #14115
Description
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 newreference target not foundwarnings 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
Activity
saimn commentedon Dec 6, 2022
Also, this is related to how we define our public API (#13910). We expect people to import everything from the top-level sub-packages, so should
astropy.coordinates.builtin_framesappear in the API docs (https://docs.astropy.org/en/latest/coordinates/#module-astropy.coordinates.builtin_frames) ? It appears here because of the convenient way to document related functions/classes withautomodapi, but maybe that should be done with manual directives instead.pllim commentedon Dec 6, 2022
If it is just a matter of some manual doc directives and we can unpin maxversion of Sphinx, I'll call that a big win, so 👍 for manual directives where needed.
And eventually if we go with an entirely new theme for RTD, then maybe we won't even use automodapi anymore, see astropy/astropy-sphinx-theme#29
mhvk commentedon Dec 6, 2022
Good point that, indeed, logically if we want people to import from the sub-package top levels, it is not obvious that it makes much sense to give full API for the lower-level ones -- really, that is mostly helpful for developers. And it is good to be able to describe a class as
u.Quantityinstead ofastropy.units.quantity.Quantity.But from the sphinx comment you linked to, it looks like the main problem is in fact that at times we ask for API documentation of more than the top-level (
astropy.units.LogUnit) and definition-level (astropy.units.function.logarithmic.LogUnit); I think it is in fact fine to not have an index that includesastropy.units.function.LogUnit-- or perhaps even not discussastropy.units.functionat all.I'll see if I can get
astropy.unitsto behave at least and will report back...mhvk commentedon Dec 6, 2022
Yes, got
astropy.unitsto behave...saimn commentedon Dec 6, 2022
Yes indeed, the comment on Sphinx explains that better than me :). There is this alias thing but only one alias is possible (without a warning), and the problem is that we have three levels here:
https://docs.astropy.org/en/latest/api/astropy.units.LogUnit.html
https://docs.astropy.org/en/latest/api/astropy.units.function.LogUnit.html
https://docs.astropy.org/en/latest/api/astropy.units.function.logarithmic.LogUnit.html
saimn commentedon Dec 6, 2022
Just to be clear, the theme is independent from the way to document the API (which generates some RST directives for Sphinx's autodoc plugin). But I'm 👍 on moving to pydata-sphinx-theme which is better maintained than our theme and already used by many pydata projects (numpy, scipy etc.).
mhvk commentedon Dec 6, 2022
@saimn - indeed, I got
unitsto work by removing the "middle" level -- in your attempt, I think you had mistakenly taken out the lower one -- and also by changing a few references in the docs to point to the canonical level.saimn commentedon Dec 6, 2022
Oh, so you removed the
units.functionone ? Yeah, makes sense now.mhvk commentedon Dec 6, 2022
Yes. Also,
wcswas just a problem with links inside the file not going to canonical. Now on tocoordinates-- which is a grand mess...