Repository navigation
Downstream docs build failing due to 7.1.0 release #18221
Description
Description
It looks like the specutils docs builds have been failing since Astropy's 7.1 release, due to two errors. First, I was getting
/home/docs/checkouts/readthedocs.org/user_builds/specutils/conda/stable/lib/python3.11/site-packages/astropy/units/quantity.py:docstring of astropy.units.quantity.Quantity.decompose:1: WARNING: py:class reference target not found: UnitBase [ref.class]
(see this build), and after adding UnitBase to our nitpick-exceptions file, ran into a second error:
/home/docs/checkouts/readthedocs.org/user_builds/specutils/conda/1220/lib/python3.11/site-packages/astropy/config/configuration.py:docstring of astropy.config.configuration.ConfigNamespace.items:1: WARNING: py:class reference target not found: ConfigItem [ref.class]
(see this build). After adding another nitpick-exceptions entry for ConfigItem, our builds are now passing. It's not clear to me why other downstream packages (e.g., jdaviz) haven't been affected by this, possible that there's something getting used in specutils that isn't there I guess. I did confirm that the specutils docs still build successfully with astropy<7.1.
Expected behavior
Astropy classes will not cause downstream readthedocs builds to fail.
How to Reproduce
No response
Versions
From my local build:
platform
platform.platform() = 'macOS-10.16-x86_64-i386-64bit'
platform.version() = 'Darwin Kernel Version 24.5.0: Tue Apr 22 19:54:49 PDT 2025; root:xnu-11417.121.6~2/RELEASE_ARM64_T6000'
platform.python_version() = '3.12.4'
packages
astropy 7.1.0
numpy 2.2.4
scipy 1.15.2
matplotlib 3.10.1
pandas 2.2.3
pyerfa 2.0.1.5
Activity
pllim commentedon Jun 5, 2025
The config one was introduced by
config#17546 (read the convo there for all the hot discussions)which also bit astroquery
The overall impact downstream varies because it depends on how much downstream is inheriting the affected parent classes API docs peppered with typing.
eerovaher commentedon Jun 5, 2025
First of all it should be pointed out that in our documentation Sphinx is able to resolve the links to both
UnitBasein theQuantity.decompose()signature and also toConfigItemin theConfigNamespace.items()signature, which is why we didn't expect this to cause problems downstream.These problems occur because of a combination of two factors. One is that we have been placing typing-only imports in
if TYPE_CHECKINGblocks. The other is that Sphinx cannot handle non-runtime type imports properly. Fixing the Sphinx bugs should solve the problem, but apparently many people have looked at the Sphinx code and despaired, so we shouldn't expect that to happen in the near future. We should therefore solve the problem by replacingif TYPE_CHECKINGblocks with runtime imports whenever possible.@rosteen, can you check if #18191 would allow your documentation build to succeed without having to suppress the warnings?
rosteen commentedon Jun 5, 2025
It looks like the specutils docs build successfully with that PR installed, without needed the nitpick-exceptions 👍
Backport PR astropy#18329: Avoid stringified type annotations in `units`