executablebooks
Launch with JupyterLite and RetroLite
We got bogged down in the original PR[^1] and I don't have permissions to push to the original branch, so I've opened this one up where we can keep iterating and ported the commit history over to here.
This PR adds support for jupyterlite-sphinx as a "launch button". There are still some things to improve that need working out:
To do
- [ ] It takes a lot longer to build the Sphinx site when this is installed, we should double-check this is intended.
- [ ] Our docs don't have any
.ipynbfiles so we can't test that this works. We should add one just for a reference in the examples. - [ ] It's unclear how the path linking works - it seems to copy over just the top-most folder but we need to copy over the full folder structure of the docs, maybe there's a way to do this.
cc @martinrenou in case he has ideas for any of these, or thoughts on how we could get this working with the "launch buttons" in Jupyter Book.
[^1]: - ref: https://github.com/executablebooks/sphinx-book-theme/pull/558
/cc @jtpio.
Getting this in here would get this into Jupyter Book, which would be a huge benefit
I wanna say that @martinrenou was doing a lot of work on jupyterlite-sphinx too? We were chatting a bit about it at the jupyterlite meeeting which is what inspired me to breathe life into this PR again haha
In terms of user experience, I imagine something like the following:
- a user is reading a Jupyter Book via an HTML view;
- they click a link to another page of the book and they are transported to that page;
- they open the book into JupyterLite and that page opens as a notebook in JupyterLite. But should this be as a notebook in a JupyerLab environment, or straight onto a full page RetroLab notebook? (In the settings, should there be a distinction between open in JupyterLite/JupyterLab, or open in JupyterLite/RetorLab?)
[I note that all source pages in the book source could be converted to .ipynb using Jupytext, which would allow them all to be opened (and editied) in JupyterLite as notebooks.]
- a link in a notebook in the JupyterLite environment should open to where? The notebook in JupyterLite, or the original HTML book page?
My original intention was simply to be able to run the code in a Jupyter Book page in a browser-based execution environment. When Thebe hits with JupyerLite support, that will provide another way of executing code in-broweser.
The JupyterLite approach (Lab or Retro) means you can edit the notebooks and persist changes in browser storage, whereas the Thebe approach limits you to changing just code cell text and not persisting code changes.
If a user edits the notebook and saves it to browser storage, there may be a mismatch between the saved, edited notebook and the rendered Jupyter Book/HTML page. (Loosely related: https://github.com/executablebooks/jupyter-book/issues/1459 )
@choldgraf @stevejpurves would you be able to bring me up to speed w.r.t whether this is the direction that we want to take jupyterlite in Jupyter Book (via sphinx-book-theme?)
One issue I've noted with jupyterlite is that it doesn't seem to behave very well if it's down a path. eg if you publish a Jupyter Book on user.github.io/repo and put a Jupyterlite instance in user.github.io/repo/jupyterlite, it often errors. Whereas it seems to be happy on user.github.io/repo/.
My 2 cents: having the "launch functionality" baked into the HTML theme is an anti-pattern, I'd rather have it handled in a more centralized place that many themes could use (e.g. so that a theme would have access to the URL needed to direct users to a JupyterLite / Binder / etc session, and could place that URL wherever they wanted in the UI). But it's baked into the book theme now so that's where people have been adding functionality.
Just to say - I hacked this by putting a Makefile target in to do the JupyterLite build, - https://github.com/odsti/cfd-textbook/commit/0c5d91c - and doing a minimal patch to this repo - https://github.com/matthew-brett/sphinx-book-theme/commit/1892593 - result e.g. here: https://odsti.github.io/cfd-textbook/using_jupyter.html
