diff --git a/docs/conf.py b/docs/conf.py index b9fd713f..f323bb3b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,6 +111,7 @@ "binderhub_url": "https://mybinder.org", "colab_url": "https://colab.research.google.com/", "deepnote_url": "https://deepnote.com/", + "retrolite_url": "/lite/retro/notebooks/", "notebook_interface": "jupyterlab", "thebe": True, # "jupyterhub_url": "https://datahub.berkeley.edu", # For testing diff --git a/docs/launch.md b/docs/launch.md index 476f8077..13cd9732 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -85,7 +85,56 @@ html_theme_options = { This will create a new Deepnote project every time you click the launch button. ``` +## JupyterLite and RetroLite +```{warning} +JupyterLite and RetroLite are experimental, and their behavior and configuration +may change over time! +Please provide feedback and suggestions. +``` + +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/" + }, + ... +} +``` +[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/" + }, + ... +} +``` ## Live code cells with Thebe [Thebe](http://thebe.readthedocs.org/) converts your static code blocks into diff --git a/src/sphinx_book_theme/header_buttons/launch.py b/src/sphinx_book_theme/header_buttons/launch.py index c5b220b0..96b33162 100644 --- a/src/sphinx_book_theme/header_buttons/launch.py +++ b/src/sphinx_book_theme/header_buttons/launch.py @@ -103,6 +103,9 @@ def add_launch_buttons( binderhub_url = launch_buttons.get("binderhub_url", "").strip("/") colab_url = launch_buttons.get("colab_url", "").strip("/") deepnote_url = launch_buttons.get("deepnote_url", "").strip("/") + # retrolite_url could be absolute but without a domain, so we only + # strip trailing slashes, not leading ones + retrolite_url = launch_buttons.get("retrolite_url", "").rstrip("/") if binderhub_url: url = ( f"{binderhub_url}/v2/gh/{org}/{repo}/{branch}?" @@ -161,6 +164,18 @@ def add_launch_buttons( } ) + if retrolite_url: + url = f"{retrolite_url}?path={path_rel_repo}" + launch_buttons_list.append( + { + "type": "link", + "text": "RetroLite", + "tooltip": "Launch via RetroLite", + "icon": "_static/images/logo_jupyterlite.svg", + "url": url, + } + ) + # Add thebe flag in context if launch_buttons.get("thebe", False): launch_buttons_list.append( diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/static/images/logo_jupyterlite.svg b/src/sphinx_book_theme/theme/sphinx_book_theme/static/images/logo_jupyterlite.svg new file mode 100644 index 00000000..09e821f6 --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/static/images/logo_jupyterlite.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/tests/sites/base/conf.py b/tests/sites/base/conf.py index c778039b..3e7f518d 100644 --- a/tests/sites/base/conf.py +++ b/tests/sites/base/conf.py @@ -27,6 +27,7 @@ "jupyterhub_url": "https://datahub.berkeley.edu", "colab_url": "https://colab.research.google.com", "deepnote_url": "https://deepnote.com", + "retrolite_url": "/lite/retro/notebooks/", "notebook_interface": "jupyterlab", "thebe": True, },