Using the current dev version with Jupyter Book

[psychemedia]

Context

I'm hoping to return to using Jupyter Book and thebe to do some interactive learning materials demo with a JupyterLite backand and was wondering what the simplest route to getting started for non-developers is.

IIRC, the process used to be pip install jupyter-book thebe, a simple _config.yml and _toc.yml file, a markdown file with a jupytext header, and a {code-cell} admonition block with the code intended for execution, and a simple thebe setting in the confg file to use MyBinder. But I'm not sure how to get started now?

The PyPi package is the legacy (pre-JupyterLite) version, and this repo does not appear to something that is intended to be installed as pip install https://github.com/executablebooks/thebe/archive/refs/heads/main.zip.

I note there is a sphinx-thebe package, but it also looks to be a legacy package without JupyterLite backend support.

Proposal

Dead simple instructions for building a Jupyter Book with thebe JupyterLite support.

I'm happy to try to help put docs together around a set of bare bones steps, and maybe even have a go at the sphinx-thebe extension to make things easier for non-devs, but at the moment I'm not sure what's a pragmatic way to get started.

Tasks and updates

No response

[psychemedia]

I wonder.. would the simplest way be a sphinx-theme that extends sphinx_book_theme and loads in the additional assets?

[stevejpurves]

Hi @psychemedia!

You're right in that thebe is not a python package, and can't be installed from pypi.

The integration of the 0.9.0-rc.X branch back into jbook untested so far, I've been focussing on the integration into mystmd which is a few steps ahead.

But I believe getting sphinx-thebe to use the latest 0.9.0-rc.9 version and testing from there is the way forward. API and behaviour should be the same as the 0.8.x branch but it really needs tested before anything could be released.

So I believe that one way forward would be to (give mystmd a try :) or) get your jbook up and running locally with thebe, and then probably make a local install of sphinx-thebe (git clone ..., then pip install -e sphinx-thebe), bump the THEBE_VERSION (here) and test from there.

Regarding juptyerlite support though:

1. this probably needs changes in sphinx-book-theme to allow an additional thebe option through
2. thebe-lite was working and pretty stable for a while until recently, where an upgrade to ipywidgets has broken things (see thebe-lite demo not working due to missing ipywidgets wheel #689) - to date this has been a simple case of updating the dependencies, but it looks like the some of the jupyterlab/lite internal classes have changed meaning it needs a little more work than that.

In the meantime, getting jbook built against 0.9.0-rc.x and binder is still moving in the right direction, enabling jupyterlite then becomes a matter of getting the additional option plumbed in.

[psychemedia]

Thanks for those tips.. is mystmd likely to be the thing that has traction over the short medium term. (In my insitution, we're looking for things that if they're not ready now are a good bet over 6 month-2year + time frames. (Should I be thinking that Jupyter Book is sunsetting?)

[psychemedia]

Just tried to use myst CLI, but I have several admonition types in my docs that use 3rd party and my own Sphinx extensions. Learning how to to get a node development environment running, as well as trying to figure out how how to write myst cli or parser extensions, is really beyond me. So I guess I'm locked in to the Sphinx route.

[michaelweinold]

Hey, @stevejpurves - I saw that you opened:

• sphinx-thebe 0.3.0-rc.0 to enable testing of thebe 0.9.0-rc.x executablebooks/sphinx-thebe#65

over in the sphinx-thebe repo. But if I understand you correctly:

this probably needs changes in sphinx-book-theme to allow an additional thebe option through

Using sphinx-thebe with thebe-lite (XEUS-Python-Kernel) in a jupyterbook would require additional changes to both (?) sphinx-thebe and jupyterbook? Or would an options in sphinx-thebe passthrough be enough:

• implement passthrough configuration executablebooks/sphinx-thebe#25

?