APE to discuss astropy doc infrastructure revamp

[pllim]

trafficstars

Ideas were floated in Astropy Coordination Meeting 2025.

Motivation: API doc is a pain with current infrastructure for those who love typing. Furthermore, sphinx-automodapi is under-maintained and has problem playing catch-up.

Alternatives discussed:

• https://github.com/readthedocs/sphinx-autoapi
• https://myst-parser.readthedocs.io
  • Only does narrative docs, but has some plugins that do API docs.
  • Numpy is looking into switching to this for their utorials. Scikit-image is looking at switching their documentation to this as well.
  • Brigitta: It's more complex as the words are overloaded. MyST markdown is a markdown flavour, and then there are two sets of machinery to make it work with Sphinx, and most recently a whole new engine that doesn't require Sphinx. I'm about to deploy some docs sites with mystmd (the new engine), and will look into switching the astroquery and pyvo docs to use it (API docs with it is still rather experimental and it's not clear if all the things we currently use from Sphinx is all supported). But we already switch with e.g. the Turing Way (which arguably the easiest as there is no code nor API docs to deal with); and then we also actively looking into if we could retire the Scientific Python hugo theme in favour of a full, myst only solution.
  • Apparently this is extensively covered in Scipy 2025 conference, so maybe check out the relevant talks on YouTube if they are available.
• https://www.mkdocs.org/
  • Common in the ML world, which might mean the $$ is there

Cons:

• Might break intersphinx (ref) and linkcheck (direct URL) downstream.
• Stretch what little resources we have even thinner.
• By the time we are done, the next new shiny thing might appear, and then do we do this all over again?

All the implications must be explored carefully in this APE.

This APE can have proof-of-concept PR(s) applying alternative(s) of choice to fix up https://github.com/astropy/astropy/pull/17978 as a feasibility study.