enable interactive exploration of examples using jupyterlite-sphinx - #10299
enable interactive exploration of examples using jupyterlite-sphinx#10299keewis wants to merge 52 commits into
jupyterlite-sphinx#10299Conversation
|
Thank you for reporting the bug and playing around with it upstream, @keewis! It should be fixed with a 0.20.1 release, but please feel free to test it from my fork if you'd like to, just in case. I confirm that it resolves the original reproducer, by the way! |
I'm slightly curious about this point, though – I imagine one would need to start a server to view the Sphinx docs anyway? |
github-actions
Bot
added
CI
|
you can use the |
|
Ah, yes, that wouldn't work with JupyterLite indeed. |
|
@agriyakhetarpal, do you know if it's possible to globally add a preamble cell to each example notebook? The purpose would be to import common modules and set up the environment, like we do for pytest's doctest runner |
Yes, this is currently not implemented, but it should be possible to include (I was working on a feature exactly like this some time back, but there's no PR yet). One thing I have to note here is that such code will be displayed to the user and would be included in a cell at the top of each example's generated notebook; it won't be hidden/silent, unfortunately – jupyterlite/jupyterlite#461 has some more details around this. Making some code executed in a hidden has been a long-requested feature in JupyterLite in some ways (especially for installing packages at runtime with the Pyodide kernel but not showing the cell in which is done, for example, see jupyterlite/pyodide-kernel#60). However, if you mean that each example can do simple things like |
|
I don't mind this being visible, so just inserting a code cell before / after the warning would be fine with me. I just played around with this by modifying my local installation of |
Thanks for the clarification, that works!
Nice! Just to ensure that our codes don't conflict – could you please put together a PR when you have a chance? I've just pushed my (a little incomplete and possible conflicting with yours) changes to my branch at https://github.com/agriyakhetarpal/jupyterlite-sphinx/tree/feat/generic-notebook-modifications – I last worked on this a little more than a month ago. Note that the original discussion around my changes is here: sphinx-gallery/sphinx-gallery#1427, which is where we should be settling down on the implementation after everything is done. In short, the idea was that Sphinx-Gallery offers "notebook modification functions" for its JupyterLite notebook galleries (like the way you suggest) and it also uses jupyterlite-sphinx as an optional dependency, but I believed that such functionality belongs in jupyterlite-sphinx itself, and Sphinx-Gallery can simply reuse it from us if we provide APIs to do so. I could go forward with my changes, but I don't intend to block yours at all, so please go for it or let me know what can work best! :) |
|
In the meantime, the 0.20.1 release is out: https://github.com/jupyterlite/jupyterlite-sphinx/releases/tag/v0.20.1, on both PyPI and conda-forge. |
yours is a much bigger change, but I don't think it will conflict: I modified the return value of I'll open a draft PR to show you want I mean. Edit: see jupyterlite/jupyterlite-sphinx#293 |
|
I can confirm that the examples here work in the RTD preview if I manually fill in the preamble we discussed above. If anyone's interested, it might be nice to style the buttons in a way that is in line with the sphinx theme we use. I did notice that retrying with a different example appears to re-install everything, which is a bit wasteful (but not sure how easy that would be to fix) |
github-actions
Bot
added
topic-backends
Automation
keewis
removed
topic-backends
CI
|
@agriyakhetarpal, the unresolved issue here is that In the current state, However, this means that Do you have any ideas on how to resolve this? |
Hi @keewis, I am glad to see the progress on this PR! Does https://jupyterlite-sphinx.readthedocs.io/en/stable/configuration.html#disable-the-ipynb-docs-source-binding work? Also, for the longer term, maybe something we should explore in (Commenting from my phone, so it's a bit hard to see the RTD build logs, sorry! I can take a closer look in the day) |
|
It doesn't, unfortunately.
|
|
Hmm, makes sense. I have decided to take a look by running Build logs |
|
you need to run |
|
I've experimented a bit more, and it looks like moving |
this did fail locally, not sure why it doesn't fail in CI, too.
keewis
left a comment
keewis
left a comment
There was a problem hiding this comment.
after a long time this should be ready for a final review now
| cfgrib = "*" | ||
| myst-parser = "*" | ||
| # use the official version once https://github.com/jupyterlite/jupyterlite-sphinx/pull/346 has been resolved | ||
| jupyterlite-sphinx = { version = "*", channel = "https://prefix.dev/keewis-oss" } |
There was a problem hiding this comment.
this is making use of a conda package I created using pixi publish and uploaded to prefix.dev. It contains the code from jupyterlite/jupyterlite-sphinx#346. As mentioned in the comment, once that PR has been resolved (whether that's merged, superseded, or simply because we figured out a better way), we can go back to the official version from conda-forge.
| Documentation | ||
| ~~~~~~~~~~~~~ | ||
| - Use ``jupyterlite-sphinx`` to provide interactive examples (:pull:`10299`). | ||
| By `Justus Magin <https://github.com/keewis>`_. |
There was a problem hiding this comment.
this will need to be moved to the most recent release section
| - https://prefix.dev/conda-forge | ||
| dependencies: | ||
| - xeus-python | ||
| - "{{ local-package }}" |
There was a problem hiding this comment.
we can probably remove the templating step for the recipe (which would be nice, the additional step just makes this a bit trickier), but I will defer that to a separate PR
| cmd = [ | ||
| "rattler-build", | ||
| "build", | ||
| "-c", | ||
| "conda-forge", | ||
| "--recipe", | ||
| "ci/recipe/recipe.yaml", | ||
| "--output-dir", | ||
| "local_channel", | ||
| ] |
There was a problem hiding this comment.
we can probably replace this with a call to pixi publish --target-dir .
4 participants
We're already using
jupyterlitein the main website, but we could also make all the docstring examples executable usingjupyterlite-sphinx.This doesn't quite work at the moment because:
try_examplesfails if the examples sections is last jupyterlite/jupyterlite-sphinx#291 causes the build to failpython -m http.server -b 127.0.0.1, for example) such that the browser does not block http requests because of the CORS headerswhats-new.rstapi.rst