astropy: Re-enable RTD beta add-on option when we can (was: Documentation warnings missing from RTD)

Thanks everyone! Now warning shows, search works, and beta add-ons still enabled. 👏

Thanks for the clarification! I will be happy to re-enable the beta add-ons to help you test as needed, but for now, I have disabled it.

EDIT: I have also updated the issue title because the warnings now appear, so original 🔥 is resolved.

Ooookay, I think I understand what is happening here now. I took a deeper look into the code here and this is not a bug with addons, but with how addons are injected.

We perform injection of the addons with a Cloudflare worker, which removes features and JS that would have previously been injected by our build process. One of these features is the version warning. The selector used to remove these warning is far too loose and could select and remove your warning admonitions.

This explains everything, and why disabling JS didn’t resolve anything. We’ll need to patch the worker code to resolve this, @humitos has a better idea of what needs to happen there though.

Sorry to send you off in the wrong direction. If I come up with a workaround before we can patch things, I’ll also let you know here.

So, I think it is one of them beta add-ons. I disabled beta add-ons for astropy and rebuilt RTD. The warning now appears:

https://docs.astropy.org/en/latest/coordinates/inplace.html

Locally, I tried to bump versions to match what RTD has, and unable to reproduce the problem. (But it is not a completely identical env.)

I (hopefully) put in a temporary fix, just skipping this logic for your project. If you enable addons, you should immediately (give or take a cache timeout) notice addons working and your warning admonitions should not disappear. No rebuild should be required.

It’s not quite clear what exactly happening here, but just to clear up a few points to help you narrow this down:

It looks like RTD (or somebody) is rebuilding old documentation versions

This does not look to be the case. The page you linked has not been updated in our storage since 2021, for both 4.2.1/4.3.1/4.2.x versions.

We might have to deploy doc build on CircleCI and inspect the artifacts there

Your later versions have the feature disabled, but at least the 4.x releases expose the reST sources already:

• https://docs.astropy.org/en/v4.2.x/_sources/coordinates/inplace.rst.txt
• https://docs.astropy.org/en/v4.3.1/_sources/coordinates/inplace.rst.txt

I note also in the published HTML docs, the text from the warnings is not in the HTML. Meaning I inspected the online RTD source and grepped (so it is not just hidden due to some JS funny).

This does seem missing from the HTML, but the warning admonition is in the source file above.

So far, this is pointing to Sphinx/docutils not rendering the admonition for some reason.

So I don’t think theme is the problem here.

I don’t think the theme would be the problem here either. I would expect some signs of the HTML in the output even if the theme was not styling the elements. However, indirectly, any of the extensions or customizations in the Sphinx theme could be a culprit.

I suspect it is some RTD add-ons that they are injecting on their server-side that we have no control over.

Our addons do not alter admonitions or page body contents outside some additions at the end of the body. You can test this by disabling JS, you should still not see the admonition with JS disabled.

If I build the docs locally (tox -e build_docs) then the warnings are there as expected.

A couple things to try:

• Ensure that you are installing the exact same versions locally as the RTD build. The RTD builds do not use Tox, though I didn’t inspect the versions installed. You can compare the dependencies installed on the builds.
• There are a few extensions that could all be influencing the build, I would probably bet one of these are incompatible or maybe defined with differing versions.

Sorry I don’t have more guidance for you yet, but perhaps experimenting with your dependencies will help surface the problem.

FWIW astroquery and photutls too have the warnings, both in narrative docs and docstrings. I haven’t yet had the time to switch over the theme, but it should not be an issue as e.g. sunpy still has the warning while it has its theme updated

https://astroquery.readthedocs.io/en/latest/esa/hubble/hubble.html#getting-hubble-products https://photutils.readthedocs.io/en/stable/api/photutils.detection.DAOStarFinder.html#photutils.detection.DAOStarFinder https://docs.sunpy.org/en/stable/tutorial/timeseries.html#inspecting-timeseries-metadata

It looks like RTD (or somebody) is rebuilding old documentation versions and something is broken which removes the sphinx warnings. I used wayback to prove that the warnings used to be there! https://web.archive.org/web/20210624113928/https://docs.astropy.org/en/stable/coordinates/inplace.html

But no longer: https://docs.astropy.org/en/v4.3.1/coordinates/inplace.html

The build date in the latter HTML says “build_date”: “2021-08-11T21:05:57Z”.