DOC: Add support for interactive examples with jupyterlite-sphinx #20019
Conversation
github-actions
bot
added
the
Documentation
|
There's a bug in the processing of literal blocks in RST which can be seen at https://steppi.github.io/scipy/reference/generated/scipy.integrate.quad.html#scipy.integrate.quad. I've made a pull request to jupyterlite-sphinx to fix this here jupyterlite/jupyterlite-sphinx#134. Update: The example is now fixed at the link above, but you can see a screenshot of what it looked like in the linked PR. |
|
This is set up to use the jupyterlite pyodide kernel. SciPy 1.12 is not available for it yet, but when it is this could be backported to 1.12. Before merging, I could disable the interactive examples by adding ignore patterns to the file try_examples.json. The interactive examples can be re-enabled at run time by editing the version of this file which is copied to the build directory of the deployed docs. Also, the pyodide kernel loads very slowly. Executing the first cell of a notebook can take 30 seconds or more, which may be annoying to users. It may be better to switch to the xeus-kernel which has faster load times. jupyterlite-sphinx uses xeus for its own docs, jupyterlite/jupyterlite-sphinx#98. @martinRenou, do you have an opinion on the choice of kernel, and an idea of how difficult it would be to make an up-to-date SciPy available in xeus for the SciPy docs? |
steppi
changed the title
|
Interesting, it's not working in the circle ci deployment here. It works locally though. Marking as draft. I'll try to figure it out. |
|
This is great thank you @steppi! I did a quick test on mobile and it also works there 👍 For Kernel choices and other tweaks, I would do the strict minimum to have the smallest maintenance possible. We tend to customize things a bit too much making it tedious to maintain. For CircleCI, I think it's not an issue at all as we just use the rendering there to check that new docs render properly. |
|
Thanks @tupui.
OK, cool. I'm not sure yet which would have the lower maintenance burden between xeuss and pyodide, but it makes sense to pick the the one with less.
Good to know. I thought maybe it was a sign the extension wasn't working as intended, but it seems to be due to limitations in circle ci's rendered docs. |
You can already make a jupyterlite-xeus deployment with scipy 1.11 and xeus-python. I can assist you into doing it, it's quite easy actually, you just need to install jupyterlite-xeus and provide an environment.yml file containing your docs dependencies. I don't know how hard it would be to get the latest scipy on emscripten-forge (the conda channel used for the WASM environment), we should give it a try. |
|
Thanks @martinRenou. It seems like jupyterlite-xeus is the way to go. Yeah, let’s look into how to get the latest SciPy into emscripten-forge. |
steppi
force-pushed
the
interactive-docs
branch
from
cb633dd to
4e3d1ca
Compare
|
I think this is in good shape now and ready to merge if anyone wants to take a look at it. I've configured it to disable all of the interactive examples, this is just putting the framework in place, so it should be safe to do. Some more info. Scipy 1.12 hasn't made it's way into pyodide yet, though the PR for adding it, pyodide/pyodide#4499, has been approved. I mentioned the possibility of using the There have been some updates in jupyterlite-sphinx since I last posted an example.
This idea was borrowed from scikit-learn's jupyterlite interactive examples.
You can try it out at the latest deployment at the link below https://steppi.github.io/scipy/reference/ for a direct link to a specific example see https://steppi.github.io/scipy/reference/generated/scipy.integrate.quad.html#scipy.integrate.quad |
| try_examples_global_warning_text = ( | ||
| "SciPy's interactive examples with Jupyterlite are experimental and may" | ||
| " not always work as expected. Execution of cells containing imports may" | ||
| " result in large downloads (up to 60MB of content for the first import" |
There was a problem hiding this comment.
Maybe adding a note that those data will then be cached by the browser, so the following openings of notebooks will not download those data again.
There was a problem hiding this comment.
Huh. I wonder if it's something to do with the tracking settings I have in firefox, but the caching doesn't work for me. Every time I import scipy in a different examples notebook, it downloads scipy, numpy, and openblas again.
There was a problem hiding this comment.
Yeah I would keep this as is. These are "details" and until we remove the experimental note we should not give more guarantee. At most i think we could add a link to the underlying tech.
There was a problem hiding this comment.
I've been playing around with the network tab in the Firefox web console. I've turned off all tracking protection in firefox, and the caching still doesn't work for me. Every time I execute an import from scipy in a different notebook, scipy, numpy, and openblas get downloaded again. Also, total download size from hitting the button to open the notebook and importing SciPy is actually more like 130MB. I was just adding up the size of the numpy, scipy, and openblas wheels that get downloaded before.
There was a problem hiding this comment.
Something weird was going on with the 130MB, I haven't witnessed that again
doc/source/_static/try_examples.css
Outdated
There was a problem hiding this comment.
Can you instead move this to scipy.css? I would prefer if we keep a single file for custom css
There was a problem hiding this comment.
Yes, that should work.
| "jupytext", | ||
| "myst-nb", | ||
| "pooch", | ||
| "jupyterlite-sphinx>=0.12.0", |
There was a problem hiding this comment.
Please also add these in the environment.yml and also in the doc about the toolchain.
There was a problem hiding this comment.
Thanks. I missed this.
| try_examples_global_warning_text = ( | ||
| "SciPy's interactive examples with Jupyterlite are experimental and may" | ||
| " not always work as expected. Execution of cells containing imports may" | ||
| " result in large downloads (up to 60MB of content for the first import" |
There was a problem hiding this comment.
Yeah I would keep this as is. These are "details" and until we remove the experimental note we should not give more guarantee. At most i think we could add a link to the underlying tech.
|
Thanks @tupui! I've heard branching for 1.13 could be imminent, so agreed, let's just get this in. |
|
PR to get SciPy 1.12 into pyodide is merged, pyodide/pyodide#4499. When that makes it into a release I'll submit a follow-up to pin the version |
|
Super nice thanks! |
Reference issue
Closes #19729
What does this implement/fix?
This PR adds interactive examples using the TryExamplesDirective from jupyterlite-sphinx. This directive adds a button which can be pressed to swap doctest Examples sections in-place with embedded Jupyterlite notebooks. These notebooks run locally in the user's browser, adding interactivity to the examples.
Additional information
Here is a screenshot of the button
and here is a screenshot showing how things look after the button is pressed
I have an experimental deployment up at https://steppi.github.io/scipy/, if anyone wants to try it out before the docs finish building, or if the docs don't build for some reason.