diff --git a/docs/conf.py b/docs/conf.py index 22bc47f5..54f19edf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ # ones. extensions = [ "ablog", + "jupyterlite_sphinx", "myst_nb", "numpydoc", "sphinx.ext.autodoc", @@ -111,6 +112,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 @@ -153,6 +155,9 @@ "https://doi.org", # These don't resolve properly and cause SSL issues ] +# JupyterLite Configuration +jupyterlite_contents = ["./docs/"] + def setup(app): # -- To demonstrate ReadTheDocs switcher ------------------------------------- diff --git a/docs/launch.md b/docs/launch.md index d8dcc9ff..d27ca92e 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -85,6 +85,56 @@ html_theme_options = { This will create a new Deepnote project every time you click the launch button. ``` +## JupyterLite and RetroLite + +```{admonition} Experimental! +:class: warning +Behavior and configuration of JupyterLite may change over time! +``` + +[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/)** 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). + + +### 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/" + }, + ... +} +``` + +There are two different interfaces that you can activate with JupyterLite, each is described below. + +### JupyterLab + +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. + ## Live code cells with Thebe diff --git a/pyproject.toml b/pyproject.toml index fb4e4d11..9a9af7ae 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,7 @@ doc = [ "ablog~=0.10.13", "ipywidgets", "folium", + "jupyterlite-sphinx", "numpy", "matplotlib", "numpydoc", 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, },