Allow multiple JupyterHub/BinderHub instances in launch buttons

Description

Currently it is only possible to specify a single JupyterHub in the drop-down “launch” buttons. It behaves like this:

launch_buttons:
  jupyterhub_url: "your-hub-url"  # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)

However, many organizations have multiple JupyterHubs to which they direct readers. For example, an organization-wide JupyterHub and a class-based JupyterHub where only subsets of users have access to each.

It should be possible for people to specify multiple JupyterHub (or BinderHub) instances, rather than only a single one.

Benefit

This would benefit any organization that has multiple hubs running for their content. It would probably most strongly benefit organizations like universities and classes.

More generally, this could be an opportunity to streamline our launch buttons so that it was a bit simpler and more easily extendable.

Implementation

Here is our logic around populating the launch buttons, this is likely where we’d need to make a change:

https://github.com/executablebooks/sphinx-book-theme/blob/43506962d4f90e6fc74d209d72503929900d84e7/sphinx_book_theme/topbar/launchbuttons.html#L3-L32

There are two options here:

1. Make it possible for each configuration to take a list of URLs. Then you could specify a list of hub URLs like so:

   launch_buttons:
     jupyterhub_url:
       - https://hub.university1.edu
       - https://hub.university2.edu
   

2. Make launch buttons take a list, where each item must follow a spec and corresponds to one hub. This would be a bigger change, but would allow us to generalize and extend more easily. In this case, launch_buttons would take entries like so:

   launch_buttons:
   - type: jupyterhub
     url: https://hub.university1.edu
     name: Some hub name 
   - type: binderhub
     url: https://binderhub.university1.edu
     name: Some other hub name
   - type: jupyterhub
     url: https://anotherhub.university1.edu
     name: A third hub name
   

   and so on.

   The launch buttons would then be a flat list that followed the entries that were in launch_buttons.

Some examples of how this has looked elsewhere:

See the quantecon datascience one:

and the quantecon julia one:

Tasks to complete

• Decide which kind of implementation we’d like to see above
• Implement and review

[phaustin]

+1 for this – it would significantly help in sharing jupyter-books for graduate/upper-year courses and research publications that require multiple cores and a lot of memory to execute.

[jlperla]

Ah you mean you’d want people to be able to “bring their own binder configs”? That does sound useful but also complicated.

Not exactly, more like BYOBU (i.e. bring your own binder/nbgitpuller url).

I don’t think it is that difficult, in fact it is already working on those sites I posted which we tested with PIMS and syzygy . It is just making it flexible to provide text that users could copy/paste in as an option instead of forcing them to use a hardcoded one. If you are already storing the users chosen launch option in the list you proposed as a cookie, then it is not a massive change. But I think this is largely a strategic decision for not just jupyterbook but the broader jupyter community as a whole: do we see executable notebooks/books/etc. as something where the user should be able to configure where they want them to execute? I hate the idea that people get trapped into colab, github codespaces, or even a hardcoded jupyterhub myself.

can you explain what you mean by this? ipynb files work in jupyter book just fine, as does execution and integration of their outputs…

Well, if something is already in a jupyter notebook then I can execute it, but I could before. But then jupyterbook is of limited use as all it does is a prettier version of nbconvert by embedding the notebook in a html frame. Moreover, nobody wants to author the content of a textbook with jupyter notebooks if they can help it for anything nontrivial.

As soon as I use any of the amazing jupyterbook features embedded in myst/etc, I can no longer have the book “executable” So unless I am missing something, I don’t think it is an exaggeration (though I am admittedly prone to hyperbole 😃 ) to say that jupyterbook doesn’t have first-class support for jupyter notebooks at this point - or, in the absence of installing a particular extension in jupyterlab, the output isn’t even executable. But my apologies if I am missing something

Is the idea to push myst as its own format and have the plugin in jupyterlab/etc. as a parallel to jupyter notebooks? If so, I see the strategy but it seems a pretty long road to success given that you would need to get colab/sagemaker/azure notebooks/vscode jupyter extension/etc. all to support it—and I don’t see why they would have incentives to support a new format. More philosophically, I don’t see why a user should be executing the underlying markup language designed for the books themselves as it was written to have all sorts of complicated stuff for publication.

@mmcky is finding ways around this limitation, but the toolchain is very complicated rather than something central to executable books. To me, it really seems like it should be integrated into the core of the product instead of as an external and fragile toolchain - especially given all of the features like https://jupyterbook.org/interactive/launchbuttons.html#launch-buttons-for-interactivity that people will expect will work for any myst code and unless they read the docs carefully will be pretty confused.

If that is unclear, then I am happy to talk about this on a call at some point (and I have discussed this at length with @colliand previously) to explain my perspective more fully.