Jupyterlite integration #977
Conversation
|
btw I think we should to the raw html hack to make both of the launch things open in new windows, cause the current behavior is a bit confusing, but that seems orthogonal to adding jupyterlite. |
|
btw I think eventually we should use emscripten-forge: https://blog.jupyter.org/mamba-meets-jupyterlite-88ef49ac4dc8 Because pyodite will not have the most recent release when a release is made (and/or might not include less-used packages). We clearly want the docs to actually run the right version of the package, that corresponds to the docs. |
|
I'm not sure I understand the exit code 1 error, any help would be appreciated :) Edit: it's because of jupyterlite/jupyterlite-sphinx#65 |
|
Seems to mostly work on circle now, but I think you can't execute a kernel because of the way the artifacts are hosted. Console shows this error when actually trying to execute a kernel: |
|
I love this effort. Thank you so much @amueller for pushing in this direction!! I've been playing a bit with it. I don't seem to get the same errors as you :). The example "Introductory example - Plotting sin" does fire up a jupyterlab, but trying even a simple "print" in it leads to infinite busy waiting (out of a sanity check, pyiodine does work on my browser, at least the way that it is set up on the front page of numpy). On the "just_code" example, I am getting the following: |
|
I think the infinite wait is a consequence of the error. You need to open the console to see it. It's a cross-site scripting protection, I assume. Sorry I wasn't more clear when/where the error occurred. |
|
This would be a great functionality to have! I tried to resolve the conflicts to get a better idea of the status of this PR. |
|
There are warnings like the ones below when enabling jupyterlite-sphinx. As a temporary work-around I am allowing the doc build to run with warnings. Edit: I figured this is fixed by setting |
|
Not sure why the CircleCI status still seems to be pending, the build has actually finished. JupyterLite link for this example I get a similar error as in #977 (comment). Basically the kernel is unresponsive. More details about the errors below. Edit: a little bit of googling seems to indicate that this is a CircleCI-specific issue, see microsoft/playwright#18108 (comment). Chromium: Firefox: |
|
The CircleCI issue is annoying but not a blocker, it works fine locally when opening a server with I triggered another CI run to make sure the other CI failures are not spurious. |
There was a problem hiding this comment.
Looking forward to testing this on the scikit-learn example gallery.
I expect that we might want to disable jupyterlite for specific examples where we know for sure that they will not run with Pyodide in the foreseeable future (e.g. because of an extra dependencies not available for WASM).
Would it be possible to have a configuration point to set a list of examples for each to disable the launch jupyterlite button and to avoid generating the matching notebook in the jupyterlite_contents folder?
| <https://pyodide.org/en/stable/index.html>`__ environment. That means that | ||
| some non pure-Python packages may not be available, see list of `available | ||
| packages in Pyodide | ||
| <https://pyodide.org/en/stable/usage/packages-in-pyodide.html>`__. |
There was a problem hiding this comment.
Maybe you could expand this point a bit and explain that this it's possible to install extra, pure-python packages from pypi.org using the following construct:
try:
# Manually install extra dependencies when running this example with
# Pyodide:
import micropip
await micropip.install("package_name")
except ImportError:
# Assume all the dependencies are already installed when running on other
# types of hosts, such as binder.
passNot protecting this snippet against ImportError would render the example pyodide-dependent as a result.
There was a problem hiding this comment.
Note that the %pip magic is also supported in the latest JupyterLite releases: https://jupyterlite.readthedocs.io/en/latest/howto/python/packages.html#installing-packages-at-runtime
%pip install package_name
Which could help make remove this try/ except block which could be awkward to some users.
|
CI is green, I have added some documentation, I think this is ready for review. |
doc/configuration.rst
Outdated
| =============================================================== | ||
|
|
||
| Sphinx-Gallery automatically generates Jupyter notebooks for any examples built | ||
| with the gallery. `JupyterLite <https://jupyterlite.readthedocs.io>`_ makes it | ||
| with the gallery. `JupyterLite <https://jupyterlite.readthedocs.io>`__ makes it | ||
| possible to run an example in your browser. TODO mention difference with Binder? |
There was a problem hiding this comment.
| possible to run an example in your browser. TODO mention difference with Binder? | |
| possible to run an example in your browser. This is different from Binder links where | |
| the notebook is run on a server. By running in the reader's browser the startup time | |
| can be much lower compared to Binder. However some libraries or parts of some | |
| libraries do not yet work in the browser. |
How about something like this? Just an idea I had as I was reading the diff (didn't take long to write and maybe you find it useful)
There was a problem hiding this comment.
Nice thanks a lot! (I thought I tackled all the TODOs left but apparently not 😉)
…lery into jupyterlite_button
|
Ping @larsoner or @GaelVaroquaux in case you have some time to review this one! Feedback from anyone else would be welcome too of course! |
|
FWIW from someone not much involved in sphinx-gallery development, I find the current implementation looks pretty good, and that it would be better to release it as experimental and get user feedback rather than try to get things into a perfect state and wait X more month. Anyway, there are still a few open questions about packaging. If you say want to document a package with C extensions it would need to be built for emscripten/wasm32 target. Probably in CI alongside the docs, but not as part of the doc builds. So what should be best practices there would likely need to be discussed at some point (not in this PR), and the outcome of that discussion might also have an impact on how the related configuration should look like. But anyway that is the next step after getting a minimal working solution out there IMO. |
|
@lucyleeow do you have time this week to look and merge if you're happy? If not then I can look |
| <https://pyodide.org/en/latest/usage/wasm-constraints.html>`__ for some | ||
| Pyodide limitations. | ||
| - with JupyterLite environments are not as flexible as Binder, for example you | ||
| can not use a docker image but only the default `Pyodide |
There was a problem hiding this comment.
only the default Pyodide
Maybe there could be a quick mention that it's also be possible to use other kernels, for example Xeus Python: https://github.com/jupyterlite/xeus-python-kernel.
There was a problem hiding this comment.
This is a good point. I tried to focus this PR on the simplest case i.e. the Pyolite kernel, but this is certainly something which could be mentioned in a follow-up PR.
There was a problem hiding this comment.
No problem it could definitely be mentioned later (just noticed while looking at the diff).
There was a problem hiding this comment.
Especially with deeper instructions on how to package a kernel with built-in dependencies required to run the examples of a given project.
|
I took a look and this is all reasonable. I want to cut 0.12, so I'll merge this then make a release so that people can start using it! |
|
Great to see this PR merged, thanks to everyone involved! |
Fix #927.
To me replite doesn't seem that nice an experience, see discussion in #927.
This PR adds a button to launch a jupyterlite instance in a new page that contains all the example notebooks, so python/jupyter doesn't need to be reloaded to read other examples.
Currently looks like this:
And clicking that gets you to something like this:
I copy & pasted a bunch of the binder button code, this probably should be refactored and made a bit cleaner, also I feel the footer is too big and we should have the buttons next to each other (launch and download, or maybe one row for launch and one for download?)