DOC/ENH: distinguish missing packages from installed ones with incompatible versions in docs/conf.py - #20414

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.

It looks good. But is there any way to test this? Testing conf.py files within the test env they set up is kinda hard...

It's actually pretty trivial to test locally, just install sphinx via pip within a fresh env then run docs/conf.py as if a script.
This is what I get

The following packages could not be found and are required to build the documentation:
    * sphinx <9,>=8.2.0 (found incompatible version 9.1.0)
    * dask >=2024.8.0
    * sphinx-design >=0.6.1
    * pytest >=8.0.0
    * sphinx-astropy >=1.11
    * fsspec >=2023.4.0
    * sphinxcontrib-globalsubs >=0.1.1
    * matplotlib !=3.9.0
    * sphinx-changelog >=1.4.0
Please install the "docs" optional dependencies.

This is getting a bit complex and would also be useful to have for coordinated packages - I'm curious if you have any thoughts about how we could potentially factor this out? For instance, we could always have a helper function in sphinx_astropy then have:

try:
    from sphinx_astropy import assert_dependencies
except ImportError:
    <error about requiring recent sphinx_astropy>

assert_dependencies('astropy', extras='docs')

Yes it's still not a single line, but it would save quite a bit of code over a number of repos.

I don't know if it'd fit sphinx-astropy's scope, but I'd be happy to move the correct version of it there if you think it makes sense.

@astrofrog to be clear, should be proceed with this PR as is and then upstream the function ?

Yes let's not hold this up