🚀 MVP launch buttons for JupyterHub & MyBinder

[agoose77]

To close jupyter-book/mystmd#1643 and jupyter-book/mystmd#1644, this PR prototypes a launch UI. We will want to move things around in time, but this PR is designed to start design conversations.

There are some deeper conversations around environment provisioning, and execution strategies. They should be ignored for the purpose of this MVP.

As such, this PR

• Uses HEAD
• Support bring-your-own Hub/Binder
• Use frontmatter-defined binder, but require user to input URL for hub (we don't have a frontmatter field for this yet)

Open questions

• It would be nice for the launch button to be sticky, but the current Thebe example feels a bit uncoupled from the rest of the document. How can we improve this?

Next Steps

• Record Git SHA during build and expose in site config mystmd#1675
• Move Thebe UX to same button
• Support launch buttons that jump into specific blocks in JLab
• closes Allow users to launch JupyterHub or a BinderHub session with book content and the current page active mystmd#1643

[agoose77]

The first commit adds a basic launch popover from the frontmatter header icons:

I think this is a good spot for a launch button, as it's "per-document", and not too obtrusive. However, it's not necessarily a "frontmatter" feature, and perhaps is too unobtrusive.

In the long run, I'd like us to expose more features, like JupyterHub vs MyBinder, Deepnote, Colab, etc. These will probably be tabs within the popover. We should aim to support these kinds of options, but reducing the amount of input that the reader needs to handle.

For now, though, the goal of this prototype is to explore the MVP for a UX in order to identify changes in MyST-MD / MyST theme that will be necessary.

[choldgraf]

Quick thoughts from me:

• That location for a button seems natural, at least as a first step. The one other place I could imagine it would be next to the thebe button, which I think is floating to the bottom-right? But I think that could be a future enhancement.
• Agree tabs is worth exploring for different launch services. Though for now, just supporting one-or-more hard-coded BinderHub and JupyterHubs is fine.
• A "nice to have" would be allowing users to specify their own BinderHub / JupyterHub to launch, but I think that's not critical for an MVP.
• If JH doesn't have an ability to tell MyST whether it has image building functionality, let's just make the assumption that a hard-coded hub/Binder instance does, and scope the "discover if a Binder image can be built" task for a follow up

Overall - the UX you describe above seems like a good first step for an MVP - it roughly mimics the behavior of Jupyter Book and would let users get started if they were already relying on that feature.

[stevejpurves]

👍🏼

[stevejpurves]

should we generalize in our naming a bit more? as in:

git: <url>
provider: 'github'

thebe does that, as the intention is to support git interface/protocol.

or are we happy with

github: 'https://gitlab.myinstitution.org/...'

Also I realise that we only have github in the frontmatter, but I am imagining that this git info will in future come from a more dedicated frontmatter.services block or the like which may have non github specific fields, like the one I suggest there.

[agoose77]

Yes, entirely! I'm going to take inspiration from some of the jb1 config here.

[agoose77]

I think we do need to change our frontmatter; GitHub should not be the only Git repo that we can define in our frontmatter.

I would probably have frontmatter fields for github, gitlab, etc. that are normalised to a git field i.e. mystmd should know how to build canonical URLs for those providers.

[rowanc1]

💯

[agoose77]

I've added support for basic validation using Radix Form:

I think this is good to go for a WIP. I'm keen to ship this in time for AGU, so I'm not exporting it intentionally. We can also disable it by default if that provides less concern for @stevejpurves et al. to ship.

Any review welcome.

[agoose77]

@jmunroe this PR adds an analogue to the "launch" button on JB1 (rocket). As an MVP, is this useful for AGU? If so, can you provide a glance over this thread to see if anything stands out as missing?

[agoose77]

Following a conversation with James, I added a copy-to-clipboard button. This will only work in secure contexts, e.g. localhost or https sites:

[agoose77]

And now an icon for launching:

[agoose77]

I don't love this; I think instead frontmatter should be resolved according to https://mystmd.org/guide/frontmatter#table-frontmatter. But, for now, let's just get this in.

[choldgraf]

OK I finally got this working locally. Here are a few pieces of feedback

Overall: I think it's safe to ship as long as folks don't see red flags with the implementation

This feels like a useful first iteration for this functionality and I'd be fine shipping it to start getting user feedback. I think there is some big functionality missing (in particular, pre-configuring the parameters in myst.yml, and having more control over visibility of the button, the repo it points to, etc, but I think those are OK to wait for a future iteration.

Here are a few specific comments in case you have cycles for an iteration on this, but I don't think they need to block it

Add documentation somewhere

First off, I'd like to see some kind of documentation for what users should expect from this feature. This PR is all implementation, and it makes it hard to orient yourself to the expected UX. I know that this repository doesn't have any docs in it, so perhaps you can open a sister PR in mystmd (as a follow up if necessary) to document a basic workflow.

Is the Binder URL generation something we can re-use internally?

Let's say that we wanted to offer the same launch button-style functionality, but with a gallery of reports / notebooks rather than via the launch buttons. From an implementation standpoint it would be useful if we have a function that takes a page's path and a myst.yml config (or subset of config) and generates the link. That way we could re-use this function in other contexts.

Call it a BindeHub URL, or a Binder Server URL, not a Binder URL

This will avoid confusion between the Binder link that a user is copying and the BinderHub server that will build and launch the link.

Vertical line between JupyterHub / Binder ?

It might help if there were a lightweight vertical line that separated the tabs, to more naturally suggest that they are tabs and not links. Something like this:

Auto-add https:// if it's not given

This might be too much magic, but my first thought was to just type mybinder.org, but I got an error saying it wasn't a valid URL. My feeling is that if the URL doesn't start with a :// prefix, we could add https:// to the generated link rather than raising an error.

Icon spacing feels a bit weird

The icon spacing feels a little bit "off" to me. It seems to be in two groups, and the space between groups is bigger than the space within groups. Because there's no visual indicator that there are two groups, the "wide" space between them feels "off" to me.

Document that a local preview needs to include npm run build

I tried following the "working with themes" instructions here:

# In a directory with content
myst start --headless
# In myst-theme
npm run theme:book
# In another terminal, watch for changes and rebuild
npm run dev

But I think it'd be helpful to include that somebody first needs to install and build the theme for this to work. I know it's in a section above, but for a JS novice they will just be copy/pasting from code blocks. I'd suggest adding:

# In a directory with content
$ myst start --headless

# In the myst-theme directory
$ npm install
$ npm run build
$ npm run theme:book
# In another terminal in the myst-theme directory, watch for changes and rebuild
npm run dev

[agoose77]

@choldgraf thanks!

in particular, pre-configuring the parameters in myst.ym

We can't yet pull a JupyterHub URL because there's no frontmatter entry. I'm holding off on that because it's due a rework. Is this the missing config you're referring to? The rest comes from Binder settings.

Otherwise, I've actioned your point RE README, and vertical separator. The other points are hard to do in this pass for various reasons (mainly framework).

Is the Binder URL generation something we can re-use internally?

I envisage this like a custom role that accepts an xref, e.g.

{launch}`xref:references/page`

or perhaps annotating an xref
{launch}[](xref:references/page)

That would be cool!

[agoose77]

OK, I took another pass at the config, because I wasn't happy with how it was built out.

I briefly explored integrating this more closely with the existing Jupyter infrastructure ... but I think that needs a rework and therefore we're better avoiding making it more complex.

Now, this PR pulls from the project binder settings, just like the thebe button does. The JupyterHub support has some nuances:

• Can't yet define a hub URL in the config (needs user input)
• Can't yet define a branch (just uses main/master)

The latter is a technical limitation with nbgitpuller (it only supports branches, not refs), and I don't know whether the user should be able to specify a different branch to the one that the book was built from. So, if nbgitpuller isn't modified to support refs, then we'd need to store the git branch in the build information.

[choldgraf]

Nice - we can upstream some functionality into nbgitpuller if need be, but I agree that's not critical for an MVP.

That role to generate a launch link is super cool! I love it. Also makes me wish we had parameters for roles so that you could specify things like the hub URL etc to over-ride the defaults.