Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Using the current dev version with Jupyter Book #692

Open
psychemedia opened this issue Oct 18, 2023 · 5 comments
Open

Using the current dev version with Jupyter Book #692

psychemedia opened this issue Oct 18, 2023 · 5 comments

Comments

@psychemedia
Copy link
Contributor

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 psychemedia changed the title Using the current dev version with Jupyter Books Using the current dev version with Jupyter Book Oct 18, 2023
@psychemedia
Copy link
Contributor Author

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

@stevejpurves
Copy link
Collaborator

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link

Hey, @stevejpurves - I saw that you opened:

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:

?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants