Remove dependence on JQuery or explicitly include it in the theme

[choldgraf]

Context

Sphinx 6.0 is going to remove the jquery dependency by default. We use jquery a little bit in this theme, though likely not in a way that strictly requires jquery.

Here's a GitHub CS search for the $( symbol

Proposal

We should try removing any explicit dependence on jquery and replace it with document.querySelector etc if possible. If we hit some hard blocker that requires jquery, we should discuss whether to work around it or re-introduce the jquery dependency.

If we need to keep JQuery, we'll need to bundle it ourselves with this theme, and remove it from externals here:

pydata-sphinx-theme/webpack.config.js

Lines 112 to 116 in e1d4009

	externals: {
	// Define jQuery as external, this way Sphinx related javascript
	// and custom javascript like popper.js can hook into jQuery.
	jquery: "jQuery",
	},

[12rambau]

I started to look into this one and it seems bootsrap 4 is exclusively relying on jquery for js behaviours. What do you think if we update the theme requirements to use bootstrap 5 ?

[choldgraf]

I'm all for upgrading to bootstrap 5. We should probably track that in it's dedicated issue though because it might involve some discussion or decisions.

For jquery I believe there is some work on an extension that we can use to handle the jquery dependency as a short term fix (cc @humitos)

[humitos]

For jquery I believe there is some work on an extension that we can use to handle the jquery dependency as a short term fix (cc @humitos)

Thanks for the ping on this issue. We did some progress around the Sphinx jQuery extension we wanted to create and we already have a plan. We have it targeted for Q4, so I'd say that we will start working on this in the next few sprints.

Note that Sphinx 6.x release (including jQuery removal) may change its dates. In that case, we may need to pin Sphinx<6 to avoid breaking the theme. We are talking about that at sphinx-doc/sphinx#10896

[AA-Turner]

We did some progress around the Sphinx jQuery extension we wanted to create and we already have a plan.

Is this solely an extension that has app.add_js_file(<jquery>)? If so, I'm happy to publish this under the sphinx org later this week. If anything more complicated I'd need a little more info!

A

[benjaoming]

@AA-Turner I work with @humitos and we're playing a bit of ping-pong on coming up with an ideal solution for handling jQuery assets. We're quite keen on fixing the issue before it turns into actual problems, but we also believe that it should be a broader community effort.

We've opened up our proposal here: readthedocs/readthedocs.org#9665

I'm happy to publish this under the sphinx org later this week.

Would you mind elaborating what you mean here? We'd be very happy to see the proposal implemented by Sphinx maintainers. If you agree with the proposal or you have any additions or simplifications, we'd be very happy to hear from you. In case you understand it want to move forward with it, that's also 👌 👍

[AA-Turner]

Hi Ben,

I didn't hear back from you so I was working on this last night with the 6.0 beta -- I've put what I had up at https://github.com/sphinx-contrib/jquery

I'm inclined to make a release to PyPI to reserve the name, too.

It would be great to work on this with the RTD team if you're interested, I can add you as a committer to the repo/etc!

A

[benjaoming]

Hi A

I think it would be great if you can add me and @humitos to the new repo.

Best,
Ben

[benjaoming]

Everyone else reading: There are some more changes and comments on the proposal - readthedocs/readthedocs.org#9665