From 509fe482612ec0cceaf0eadd796ce61134782c28 Mon Sep 17 00:00:00 2001 From: Tony Hirst Date: Mon, 14 Mar 2022 14:42:08 +0000 Subject: [PATCH 1/7] First attempt at "Launch in RetroLite" --- docs/conf.py | 1 + docs/launch.md | 17 +++++++++++++++++ src/sphinx_book_theme/header_buttons/launch.py | 13 +++++++++++++ .../static/images/logo_jupyterlite.svg | 15 +++++++++++++++ tests/sites/base/conf.py | 1 + 5 files changed, 47 insertions(+) create mode 100644 src/sphinx_book_theme/theme/sphinx_book_theme/static/images/logo_jupyterlite.svg diff --git a/docs/conf.py b/docs/conf.py index 59f56faa..fcb4589f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -110,6 +110,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..00c90c04 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -85,6 +85,23 @@ html_theme_options = { This will create a new Deepnote project every time you click the launch button. ``` +## 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. +``` ## Live code cells with Thebe diff --git a/src/sphinx_book_theme/header_buttons/launch.py b/src/sphinx_book_theme/header_buttons/launch.py index 51c692b2..8a326138 100644 --- a/src/sphinx_book_theme/header_buttons/launch.py +++ b/src/sphinx_book_theme/header_buttons/launch.py @@ -102,6 +102,7 @@ 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 = launch_buttons.get("retrolite_url", "").strip("/") if binderhub_url: url = ( f"{binderhub_url}/v2/gh/{org}/{repo}/{branch}?" @@ -157,6 +158,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..77e87965 --- /dev/null +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/static/images/logo_jupyterlite.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + diff --git a/tests/sites/base/conf.py b/tests/sites/base/conf.py index c778039b..6ddc7a5a 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, }, From 4d0681490bc47d8c585d233627868a1dbae845e6 Mon Sep 17 00:00:00 2001 From: Tony Hirst Date: Wed, 4 May 2022 15:47:06 +0100 Subject: [PATCH 2/7] Update jupyterlite icon --- .../static/images/logo_jupyterlite.svg | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) 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 index 77e87965..09e821f6 100644 --- 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 @@ -1,15 +1,17 @@ - - - - - - + + + + + + - - + + + + + + + - From b2fa323793fcfbcec4533471883f31f9032bbfc5 Mon Sep 17 00:00:00 2001 From: Tony Hirst Date: Wed, 4 May 2022 16:06:27 +0100 Subject: [PATCH 3/7] Update jupyterlite launcher docs --- docs/launch.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/launch.md b/docs/launch.md index 00c90c04..d5590d44 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -101,6 +101,10 @@ html_theme_options = { ```{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.* ``` ## Live code cells with Thebe From 47d8875f44fe5ef112599a40b4dcfae1fa147b65 Mon Sep 17 00:00:00 2001 From: YuviPanda Date: Mon, 27 Jun 2022 15:02:11 -0700 Subject: [PATCH 4/7] Use absolute URL without domain for retrolite --- docs/conf.py | 2 +- docs/launch.md | 2 +- src/sphinx_book_theme/header_buttons/launch.py | 4 +++- tests/sites/base/conf.py | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c39aad83..f323bb3b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -111,7 +111,7 @@ "binderhub_url": "https://mybinder.org", "colab_url": "https://colab.research.google.com/", "deepnote_url": "https://deepnote.com/", - "retrolite_url": "./lite/retro/notebooks/", + "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 d5590d44..94ae11f9 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -93,7 +93,7 @@ To add [RetroLite](https://jupyterlite-sphinx.readthedocs.io/en/latest/retrolite html_theme_options = { ... "launch_buttons": { - "retrolite_url": "./lite/retro/notebooks/" + "retrolite_url": "/lite/retro/notebooks/" }, ... } diff --git a/src/sphinx_book_theme/header_buttons/launch.py b/src/sphinx_book_theme/header_buttons/launch.py index 557da30e..96b33162 100644 --- a/src/sphinx_book_theme/header_buttons/launch.py +++ b/src/sphinx_book_theme/header_buttons/launch.py @@ -103,7 +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 = launch_buttons.get("retrolite_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}?" diff --git a/tests/sites/base/conf.py b/tests/sites/base/conf.py index 6ddc7a5a..3e7f518d 100644 --- a/tests/sites/base/conf.py +++ b/tests/sites/base/conf.py @@ -27,7 +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/", + "retrolite_url": "/lite/retro/notebooks/", "notebook_interface": "jupyterlab", "thebe": True, }, From bd30377a683836091877fb3e0bfe00407e23fced Mon Sep 17 00:00:00 2001 From: Paul Ivanov Date: Fri, 1 Jul 2022 14:25:55 -0700 Subject: [PATCH 5/7] incorporate @choldgraf's changes Co-authored-by: Chris Holdgraf --- docs/launch.md | 46 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/launch.md b/docs/launch.md index 94ae11f9..13cd9732 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -85,7 +85,13 @@ html_theme_options = { This will create a new Deepnote project every time you click the launch button. ``` -## RetroLite +## 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: @@ -98,15 +104,37 @@ html_theme_options = { ... } ``` - -```{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](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 From 011ce6c82c32de5922bc7eaaeaaa2bdeffba03cf Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 7 Dec 2022 17:58:12 +0100 Subject: [PATCH 6/7] Clean up docs --- docs/conf.py | 5 +++++ docs/launch.md | 47 ++++++++++++++++++++++++----------------------- pyproject.toml | 1 + 3 files changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7c1b8d36..d0488cb7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ # ones. extensions = [ "ablog", + "jupyterlite_sphinx", "myst_nb", "numpydoc", "sphinx.ext.autodoc", @@ -154,6 +155,10 @@ "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 047b3868..40200247 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -87,12 +87,24 @@ 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. +```{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 @@ -104,14 +116,13 @@ html_theme_options = { ... } ``` -[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 + +### JupyterLab + To add JupyterLab via JupyterLite to your launch buttons, use the following configuration: + ```python html_theme_options = { ... @@ -121,20 +132,10 @@ html_theme_options = { ... } ``` + 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/pyproject.toml b/pyproject.toml index 1d3ff833..8f0c4297 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,7 @@ doc = [ "ablog~=0.10.13", "ipywidgets", "folium", + "jupyterlite-sphinx", "numpy", "matplotlib", "numpydoc", From 37dc24992c3a86b9905b2098eee79890ae5af9c7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 9 Dec 2022 14:55:33 +0000 Subject: [PATCH 7/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/conf.py | 1 - docs/launch.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d0488cb7..54f19edf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -159,7 +159,6 @@ jupyterlite_contents = ["./docs/"] - def setup(app): # -- To demonstrate ReadTheDocs switcher ------------------------------------- # This links a few JS and CSS files that mimic the environment that RTD uses diff --git a/docs/launch.md b/docs/launch.md index 40200247..d27ca92e 100644 --- a/docs/launch.md +++ b/docs/launch.md @@ -99,7 +99,7 @@ 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. + 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).