Launch in jupyterlite

[psychemedia]

Update to theme to demonstrate a RetroLite launcher that allows you to open a page generated from a notebook as a notebook in JupyterLite.

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.

Welcome to the EBP community! 🎉

[yuvipanda]

This looks pretty awesome! Any way to get this reviewed?

[yuvipanda]

here is a PR to this PR that got it working for me: ouseful-PR#3

[yuvipanda]

Once that PR lands and this lands, adding jupyterlite was trivial yuvipanda/textbook@eb4edf2

[choldgraf]

Just a couple quick suggestions to move this one forward, I think this would be really helpful for many people! Can you double-check my suggested wording to make sure it is factually incorrect? I'd be +1 on merging this in (along w/ @yuvipanda's other PR to yours)

[choldgraf]

Suggested change

	## RetroLite
	To add [RetroLite](https://jupyterlite-sphinx.readthedocs.io/en/latest/retrolite.html) links to your page, add the following configuration:
	```python
	html_theme_options = {
	...
	"launch_buttons": {
	"retrolite_url": "./lite/retro/notebooks/"
	},
	...
	}
	```
	```{warning}
	This requires installation of [`jupyterlite-sphinx`](https://jupyterlite-sphinx.readthedocs.io/) and the publication of a RetroLite environment as part of your published Jupyter Book environment.
	You __must__ also publish the Jupyter Book / JupyterLite environemt via a webserver in order to access the JupyterLite environment.
	*As of `jupyterlite-sphinx==0.4.7, you will have to manually ensure that notenook files are copied over to the `_build/html/lite/files` directory in order to work with them in JupyterLite.*
	```
	## JupyterLite and RetroLite
	```{warning}
	JupyterLite and RetroLite are experimental, and their behavior and configuration may change over time!
	Please provide feedback and suggestions.
	```
	[JupyterLite](https://jupyterlite.readthedocs.io/) allows you to run a Jupyter environment entirely in the browser via [WebAssembly](https://webassembly.org/) and [Pyodide](https://pyodide.org/en/stable/).
	To use JupyterLite in your launch buttons, you'll first need to take these steps:
	1. **Install [`jupyterlite-sphinx`](https://jupyterlite-sphinx.readthedocs.io/)**. And configure it to publish a JupyterLab environment as part of your published Jupyter Book environment by [following the installation instructions](https://jupyterlite-sphinx.readthedocs.io/en/latest/installation.html).
	2. **Configure JupyterLite Sphinx to use your site content as a folder**. You can configure JupyterLite Sphinx to look for notebooks in a specified directory. Put the notebooks you wish to expose in that directory, and [follow these configuration instructions](https://jupyterlite-sphinx.readthedocs.io/en/latest/configuration.html#jupyterlite-content).
	```
	There are two different interfaces that you can activate with JupyterLite, each is described below.
	### JupyterLab via JupyterLite
	To add JupyterLab via JupyterLite to your launch buttons, use the following configuration:
	```python
	html_theme_options = {
	...
	"launch_buttons": {
	"jupyterlite_url": "/lite/lab/notebooks/"
	},
	...
	}
	```
	Where `notebooks/` is a folder with a collection of Jupyter Notebooks you'd like to serve with JupyterLite.
	### RetroLab via JupyterLite
	RetroLab mimics the classic Jupyter Notebook interface, but using JupyterLab components.
	It will be the default Notebook interface in the near future.
	To add RetroLab via JupyterLite to your launch buttons, use the following configuration:
	```python
	html_theme_options = {
	...
	"launch_buttons": {
	"jupyterlite_url": "/lite/retro/notebooks/"
	},
	...
	}
	```

[choldgraf]

Some suggestions to flesh this out a bit more, since most people won't know how to use JupyterLite or what it is

[yuvipanda]

the URL should be absolute (/lite/retro/notebooks/, without the . prefix) for it to work. This was fixed in my PR

[choldgraf]

Could we call this jupyterlite_url for now, since that is the "parent" tool, and document how to make it connect w/ retro vs. lab etc in the text below?

[psychemedia]

My thinking was separate URLs for whether the launch was into retrolab or open notebook in jupyterlab/jupyterlite

[psychemedia]

I opened an issue some time ago in jupyterlite repo wrt to having a discrete *lite identities for these two UIs, motivated in part by this PR: jupyterlite/jupyterlite#549

[choldgraf]

I think where we're heading for the launch button config is to provide a list of configuration snippets that each map onto one button, so I'd imagine this will eventually look like:

"launch_buttons": [
    {"type": "jupyterlite", "root": "/lite", "prefix": "/lab", "name": "Launch JupyterLite"},
    {"type": "jupyterlite", "root": "/lite", "prefix": "/retro", "name": "Launch RetroLite"},
    {"type": "jupyterhub", "url": "https://hub1.myorg.org", "name": "Launch JupyterHub One"},
    {"type": "jupyterhub", "url": "https://hub2.myorg.org", "name": "Launch JupyterHub Two"},
]

So that's why I was thinking we'd just have one name for it, does that make sense or do you think it would make more sense to use type: "jupyterlite" and type: "retrolite"?

[psychemedia]

IIRC, there was also a workflow issue in making sure files got copied over to the build/distribution directory. I think jupyterlite/jupyterlite-sphinx@944ccf4 helps in this respect (I haven't tried, but it looks like you can specify a directory from which files are copied). It would perhaps be cleaner on the jupyterlite-sphinx side if you could also enable files that are build from from the Sphinx toc file get copied over if they are eeg .ipynb notebooks?

[choldgraf]

Yeah - it looks like JupyterLite has the assumption of a user-provided folder of notebooks to launch JupyterLite with. What we want is to ensure that any page that is .ipynb also exists in the JupyterLite contents folder with the relative path maintained relative to the docs root

[choldgraf]

I'm gonna close this one and take development over to this PR (after porting over commit history):

• Launch with JupyterLite and RetroLite #655

I tried this out again and I think there's still some stuff to figure out before we can merge it in (e.g. the paths in the links don't seem to work properly right now).