Unusable Search utility with sphinx=6.1.3

[valeriupredoi]

Hey guys, first off many thanks for a great theme! We've been using it for a long while now, as well as many other software packages - great work!

Second - the meat of the issue: we've discovered that the Search utility doesn't work no more - it shows "Searching..." but that never ends, it keeps going ad infinitum. This is happening with sphinx=6.1.3 (latest) and any sphinx_rtd_theme (currently that's 1.2.0), both installed from conda-forge. With an older sphnix, and our RTD env builder picks only sphinx=5.0, even though there are slightly newer, and any sphinx_rtd_theme (I tested 1.1.1 and 1.2.0) makes the problem go away and the search works as expected. I reckon there is some form of budgery going on there at the interface - we have now pinned sphinx in our env so we don't pick up this problem anymore, but it'd be good if you could look into it so the theme works well with the latest sphinx. Let me know if I can help in any way! More details below:

• documentation built with sphinx=6.1.3 and latest theme (1.2.0): https://docs.esmvaltool.org/en/v2.8.0/
• documentation built with sphinx=5.0 and latest theme (1.2.0): https://readthedocs.org/projects/esmvaltool/builds/19945256/
• PR where we pin sphinx: Pin sphinx !=6.1.3 (avoid non-functional Search utility on readthedocs) ESMValGroup/ESMValTool#3142

Cheers 🍺

[benjaoming]

Hi @valeriupredoi 👋

Thanks for the report!

• Can you use the web developer tools in your browser to test if this is because jQuery isn't loaded? You could check if $ is defined or see if there are JavaScript errors that indicate this issue.

• Does Sphinx 6.1.0 and 6.0.x produce the same results?

[valeriupredoi]

hi @benjaoming many thanks for getting back, mate! Indeed I see quite a few errors - related to jQuery (I think, sorry, am pretty obtuse when it comes to web devel), see attached log
console-export-2023-3-30_11-42-18.txt

[valeriupredoi]

let me get back to you about sphinx versions 6.x.x, <6.1.3 - I need to rerun the builds 👍

[benjaoming]

Yup, it's jQuery that is not loaded... Uncaught ReferenceError: jQuery is not defined

After looking at your configuration, it see that you're probably affected by #1448

The workaround is to add sphinxcontrib.jquery to extensions in conf.py

I'm gonna close this, but feel free to reopen if the workaround doesn't work 👍

[valeriupredoi]

great! Many thanks, mate! I shall do that, then retest, then either come back with a 🍺 or reopen 😁

[benjaoming]

haha cheers 🍺

[valeriupredoi]

incidentally, I managed to test with sphinx=6.0.0 before you gave me the workaround - see build - and it's the same story, so it appears any sphinx>=6 is buggering us up 👍

[benjaoming]

it's complicated :)

[valeriupredoi]

you, sir, are a legend - the build with latest sphinx and the additional extension is now working very well, and the Search works too, many thanks 🍺 (see https://readthedocs.org/projects/esmvaltool/builds/19956050/ )

[benjaoming]

THANKS! And thanks for the great feedback. I'm sorry that tool upgrades are sometimes annoying like this. But we have the fix ready, so hopefully we can get it finished and released soon.

I opened #1452 so hopefully it's easy for others to find and solve similar cases until then 👍

Very nice project btw! Thank you for doing important work to understand climate change 🙏

[valeriupredoi]

many thanks @benjaoming - no problemo about new pkgs etc, that's why we have these issues for, and it's always a pleasure to work with devs like you: responsive, and with a fix at ready! A virtual 🍺 to you mate