[DOCS] Adding introductory documentation to the launch buttons

[choldgraf]

References

In preparation for adding a retrolab tutorial to the top row of try.jupyter.org, I thought it'd be helpful to add two quick introductory notebooks for the Lab / Retrolab buttons on the JupyterLite docs. This way, users see some content when they click the button, and can have a few pointers in the right direction. This may be a short-term solution until we can flesh out some more introductory content that is fitting for try.jupyter.org, but what do people think about this as a first step?

• Temporarily use JupyterLite for high-traffic links to mybinder.org jupyter/jupyter.github.io#513
• Identify credits for the next year of gke.mybinder.org jupyterhub/team-compass#463

Documentation changes

• There are now two lightweight "introductory" notebooks that are meant to guide people on their first steps with the interfaces.
• The buttons in the top left of the docs now open an intro notebook when JupyterLite is loaded.

[github-actions]

👈 Try it on ReadTheDocs

[bollwyvl]

This is good content.

Given the size breakdown on that other issue, I don't think we'd necessarily want to always point directly at a particular python notebook with its 30mb load as the very first introduction. If it was a notebook, a JS kernel notebook would be far lighter weight, and is more likely to stay in this repo, and could still make some pretties with e.g. vega. However, more likely, we'd want to rework the prose into steps of a tour, and start that off.

Over on https://ipydrawio.readthedocs.io and https://pidgy.readthedocs.io i've played around with some other approaches to flexibly launching the demo with some URL-based configuring... perhaps we consider some alternate forms, including offering all of the examples as potential starting points.

More broadly: even if we did bring the capability into try.jupyter.org, this project's main is not ready to be the destination, even if the released package could build a site, deployed on try.jupyter.org/lite/, for example, that was. We do what we can to keep it working here, but you know...

[choldgraf]

Gotcha - makes sense to me. Do you think we should close this PR? Or rework the content somehow? I suspect that many people will land on the jupyterlite docs and just click one of the try buttons in the top left, since that's a high eyeballs spot, and might be confused at the lack of context since they haven't read anything else.

I didn't realize size was a concern (WASM and jupyterlite continues to work in mysterious ways to me haha). Maybe it should just be a markdown file?

[jtpio]

Thanks @choldgraf!

Do you think we should close this PR? Or rework the content somehow?

Probably we can still keep the intro.ipynb and intro-retro.ipynb as they would show up in the file browser at the top-level.

Another idea would be to open examples/README.md by default with links to these notebooks. And iterate a bit on the README.md to make it more like a proper gallery of examples (could be done at a later stage).

[choldgraf]

Another idea would be to open examples/README.md by default with links to these notebooks. And iterate a bit on the README.md to make it more like a proper gallery of examples (could be done at a later stage).

This sounds like a nice idea - let me know if you'd like this in the current PR or not. Basically just having any kind of landing page would I think be a benefit to the user, even if it just a sentence or two with pointers

[jtpio]

@choldgraf if you would like to do it in this PR that would be great, thanks!

[choldgraf]

ok - can you give me an idea of what kind of content you think is best there? Something like a few paragraphs about JupyterLite in general with pointers to the intro notebooks? Anything else?

[jtpio]

That would already be a good introduction yes.

There was also some previous discussions about this in #168 and related issues.

[jtpio]

Just rebased onto main to grab the latest updates.

Testing on RTD, opening a notebook by default doesn't feel too heavy at first. Although it's true some dependencies are pulled, and the first cell run still takes some time but it's a bit faster now thanks to #433.

[jtpio]

However there seems to be a micropip related issue when opening the notebook with the new Pyodide 0.19 and lite 0.1.0a19:

But this does not seem to be a problem when testing on https://jupyterlite.github.io/demo/, which doesn't pre-cache the wheels:

[jtpio]

However there seems to be a micropip related issue when opening the notebook with the new Pyodide 0.19 and lite 0.1.0a19:

Ah nevermind that, this was most likely a caching issue. Trying again in a private window seems to work fine:

startup-open-notebook.mp4

[bollwyvl]

Format intro notebooks

I've been wondering: we should probably add a no-op nbconvert --to notebook to our linter, as the "one line of JSON" is even less ergonomic than a regular ipynb 🤣

[jtpio]

Since this is good content, I would be in favor of getting this in.

We can keep the demo link in the project description of the repo (and similar links) as it is now without the ?path=:

cc @bollwyvl since you had a comment about loading times above

[choldgraf]

@jtpio I can probably put a quick cycle into this (say, 30 minutes) if I have a really clear idea of what new content needs to be in here, but probably don't have time to do more complex iterations. Let me know if you'd prefer to just merge it in, or if I should make some changes first

[jtpio]

Thanks @choldgraf.

Another idea would be to open examples/README.md by default with links to these notebooks. And iterate a bit on the README.md to make it more like a proper gallery of examples (could be done at a later stage).

Actually the README opens with the text editor by default for now and not the markdown preview, which makes opening that file with ?path= less interesting I believe. Although we could override the preferred factory for markdown files to open with the markdown preview on the demo ReadTheDocs deployment.

Which is why we could just keep the current content as it is with this PR, and iterate later if needed.

[jtpio]

Thanks!

[choldgraf]

thanks for the iteration and suggestions all :-)