Documentation search is broken.

[Taylor]

As you may already know, doc search is currently broken. I figured out why.

Sphinx relies on [html_root]/searchindex.js (built along with the static docs) to search. Sphinx used to load this file with jQuery, but now by default uses vanilla JS, and jQuery was removed from Sphinx in ~2022 with the release of Sphinx 6.0.0. However, pydicom uses the sphinx_rtd_theme, which forked the default Sphinx theme a long time ago and still depends on jQuery to load searchindex.js.

For some reason, in our install of Sphinx and sphinx_rtd_theme (as deployed right now and I reproduced locally) doesn't actually come with jQuery, so searchindex.js is never loaded. The easiest, hackiest fix is to simply apply this change to the built artifact doc/_build/html/search.html

  <!-- Comment out the jQuery call -->
  <!--<script>-->
    <!--jQuery(function() { Search.loadIndex("searchindex.js"); });-->
  <!--</script>-->

  <!-- Load with vanilla JS -->
  <script src="searchindex.js" defer=""></script>

Ultimately I think we might just go with a hacky fix for now, and a script to do this is pretty simple since searchindex.js is guaranteed to be generated in the root directory (of the docs build).
I really don't want to "fix" this issue because that involves us adding jQuery to the docs... I'd like sphinx_rtd_theme to remove their dependency on jQuery upstream (let's be real who needs jQuery when you have ES6?)

[Taylor]

Trying to fix it upstream readthedocs/sphinx_rtd_theme#1546

[mrbean-bremen]

Thanks for the catch and the quick investigation! Indeed an upstream fix would be the preferred way. Let's wait a bit what the maintainers of the theme are going to say.