sphinx_rtd_theme
sphinx_rtd_theme copied to clipboard
readthedocs
Remove jQuery
Sphinx will be moving to remove jQuery as a dependency. We are currently using jQuery in our JS and in the application JS, so we'll want to start thinking about doing this with vanilla JS.
Related: https://github.com/sphinx-doc/sphinx/issues/7405#issuecomment-971893132
I actually view this as a positive. I do think there's a few things to think about:
- Should we make our theme work with old Sphinx versions that include jQuery but our theme only uses vanilla JS?
- Should we major rev the theme and require new versions of Sphinx for that version of the theme?
Option 1 might be tricky but I lean in that direction.
Option 1 should be easy enough as using vanilla JS with or without jQuery creates no conflict. It would be even better if we drop support for IE11 at the same time to use ES6 without any combability concerns. It's then just be a matter of including jQuery for old Sphinx versions, but this should not affect us.
It's then just be a matter of including jQuery for old Sphinx versions, but this should not affect us.
We won't even need to do this! Sphinx handles this already. If they build with an old Sphinx, it writes jQuery to the output. We just have to make sure our theme works regardless of whether Sphinx added jQuery or not.
Yes, we should add the sphinxcontrib-jquery dependency - we need to firstly add docutils 0.18 support (since it seems to be a requirement of Sphinx 6), on top of that we can add Sphinx 6 support w/ the sphinxcontrib-jquery dependency.
I don't think that it's a good idea to remove jQuery, since we probably have projects using sphinx-rtd-theme that will anticipate that it's there. Once gone, they will break silently in bad ways.
We could, though, remove jQuery from the theme itself and replace it with vanilla JS. Any comments on this?
I have added sphinxcontrib-jquery as a dependency here: https://github.com/readthedocs/sphinx_rtd_theme/pull/1385
I don't think that it's a good idea to remove jQuery, since we probably have projects using sphinx-rtd-theme that will anticipate that it's there. Once gone, they will break silently in bad ways.
Yeah, unfortunately I think it's best to add the dependency on sphinxcontrib-jquery either way. We don't have any way of confirming how widely jQuery would be used on derivative themes. This should be a fairly significant deprecation in a fairly long list of deprecations. Moving towards vanilla JS is probably wise just for consistency, but I would probably give jQuery removal a longer grace period.
I'd definitely like to remove jQuery and a dependency sphinxcontrib-jquery, maybe we can target the latter for 2.0. So we start by softly removing jQuery, replacing it with vanially JS in 1.2 and then we can announce the deprecation with a bit of buffer until final removal?
2.0 is already overloaded, so probably not in that release. I don't think including jQuery is a huge problem, really. It's just debt we want to remove eventually, or is maybe just being Technically Correct.
I say it's fine to continue including the release here via sphinxcontrib-jquery, but we should be moving towards vanilla JS everywhere either way.