sphinx-gallery · larsoner · Mar 8, 2023 · Jul 16, 2022 · Jul 16, 2022 · Jul 16, 2022
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -41,7 +41,7 @@ jobs:
           command: |
             pip install --progress-bar off --user --upgrade --only-binary ":all:" pip setuptools
             pip install --progress-bar off --user --upgrade --only-binary ":all:" numpy matplotlib "pyqt5!=5.15.2,!=5.15.3,!=5.15.8" vtk
-            pip install --progress-bar off --user --upgrade seaborn statsmodels pillow joblib sphinx pytest traits mayavi pyvista memory_profiler "ipython!=8.7.0" plotly graphviz "docutils>=0.18"
+            pip install --progress-bar off --user --upgrade seaborn statsmodels pillow joblib sphinx pytest traits mayavi pyvista memory_profiler "ipython!=8.7.0" plotly graphviz "docutils>=0.18" jupyterlite-sphinx
             pip install --progress-bar off --user --upgrade --pre pydata-sphinx-theme
       - save_cache:
           key: cache-pip

diff --git a/.gitignore b/.gitignore
@@ -81,3 +81,6 @@ target/
 
 # Jupyter notebooks
 .ipynb_checkpoints
+
+# Default JupyterLite content
+jupyterlite_contents
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -60,7 +60,7 @@ stages:
         pip install --user --upgrade --progress-bar off "ipython!=8.7.0" numpy seaborn statsmodels matplotlib sphinx pillow pytest pytest-cov joblib "plotly>=4.0"
         pip install --user --upgrade --progress-bar off --pre pydata-sphinx-theme
         echo "Qt, plotly, VTK"
-        pip install --user --upgrade --progress-bar off pyvista "pyqt5!=5.15.8" plotly vtk
+        pip install --user --upgrade --progress-bar off pyvista "pyqt5!=5.15.8" plotly vtk jupyterlite-sphinx
         echo "Mayavi"
         pip install --user --upgrade --progress-bar off --no-build-isolation mayavi
       displayName: Setup pip environment

diff --git a/continuous_integration/azure/install.sh b/continuous_integration/azure/install.sh
@@ -15,7 +15,7 @@ if [ "$DISTRIB" == "conda" ]; then
     echo "##vso[task.prependpath]$CONDA/bin"
     export PATH=${CONDA}/bin:${PATH}
     CONDA_TO_INSTALL="python=$PYTHON_VERSION pip numpy setuptools matplotlib pillow pytest pytest-cov coverage seaborn statsmodels 'plotly>=4.0' joblib flake8 wheel libiconv graphviz memory_profiler \"ipython!=8.7.0\" pypandoc"
-    PIP_DEPENDENCIES="check-manifest"
+    PIP_DEPENDENCIES="check-manifest jupyterlite-sphinx"
     if [ "$SPHINX_VERSION" == "" ]; then
         PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx jinja2<=3.0.3"
     elif [ "$SPHINX_VERSION" == "dev" ]; then

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -15,3 +15,4 @@ plotly
 absl-py
 graphviz
 packaging
+jupyterlite-sphinx
diff --git a/doc/conf.py b/doc/conf.py
@@ -45,6 +45,7 @@
     'sphinx.ext.mathjax',
     'sphinx_gallery.gen_gallery',
     'sphinx.ext.graphviz',
+    'jupyterlite_sphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/doc/configuration.rst b/doc/configuration.rst
@@ -50,6 +50,7 @@ file:
 - ``show_memory`` (:ref:`show_memory`)
 - ``show_signature`` (:ref:`show_signature`)
 - ``binder`` (:ref:`binder_links`)
+- ``jupyterlite`` (:ref:`jupyterlite`)
 - ``promote_jupyter_magic`` (:ref:`promote_jupyter_magic`)
 - ``first_notebook_cell`` and ``last_notebook_cell`` (:ref:`own_notebook_cell`)
 - ``notebook_images`` (:ref:`notebook_images`)
@@ -1116,6 +1117,108 @@ See the Sphinx-Gallery `Sphinx configuration file
 <https://github.com/sphinx-gallery/sphinx-gallery/blob/master/doc/conf.py>`_
 for an example that uses the `public Binder server <https://mybinder.org>`_.
 
+.. _jupyterlite:
+
+Generate JupyterLite links for gallery notebooks (experimental)
+===============================================================
+
+Sphinx-Gallery automatically generates Jupyter notebooks for any examples built
+with the gallery. `JupyterLite <https://jupyterlite.readthedocs.io>`__ makes it
+possible to run an example in your browser. The functionality is quite similar
+to Binder in the sense that you will get a Jupyter environment where you can
+run the example interactively as a notebook. The main difference with Binder
+are:
+
+- with JupyterLite, the example actually runs in your browser, there is no need
+  for a separate machine in the cloud to run your Python code. That means that
+  starting a Jupyter server is genrally quicker, no need to wait for the Binder
+  image to be built
+- with JupyterLite the first imports take time. At the time of writing
+  (February 2023) ``import scipy`` can take ~15-30s. Some innocuously looking
+  Python code may just not work and break in an unexpected fashion. The Jupyter
+  kernel is based on Pyodide, see some `here
+  <https://pyodide.org/en/latest/usage/wasm-constraints.html>`__ for some
+  Pyodide limitations.
+- with JupyterLite environments are not as flexible as Binder, for example you
+  can not use a docker image but only the default `Pyodide
+  <https://pyodide.org/en/stable/index.html>`__ environment. That means that
+  some non pure-Python packages may not be available, see list of `available
+  packages in Pyodide
+  <https://pyodide.org/en/stable/usage/packages-in-pyodide.html>`__.
+
+.. warning::
+
+   JupyterLite is still beta technology and less mature than Binder, so there
+   may be instability or unexpected behaviour in the experience of users who
+   click JupyterLite links.
+
+In order to enable JupyterLite links with Sphinx-Gallery, you must install the
+`jupyterlite-sphinx <https://jupyterlite-sphinx.readthedocs.io>`_ package and
+add it to your extensions in ``conf.py``::
+
+    extensions = [
+        ...,
+        ...,
+        ...,
+        'jupyterlite_sphinx',
+    ]
+
+You can configure JupyterLite integration by setting
+``sphinx_gallery_conf['jupyterlite']`` in ``conf.py`` like this::
+
+    sphinx_gallery_conf = {
+      ...
+      'jupyterlite': {
+         'jupyterlite_contents': <str> # JupyterLite contents where to copy the example notebooks (relative to Sphinx source directory)
+         'use_jupyter_lab': <bool> # Whether JupyterLite links should start Jupyter Lab instead of the Retrolab Notebook interface.
+         }
+    }
+
+Below is a more complete explanation of each field.
+
+use_jupyter_lab (type: bool, default: ``True``)
+  Whether the default interface activated by the JupyterLite link will be for
+  Jupyter Lab or the RetroLab Notebook interface.
+
+jupyterlite_contents (type: string, default: ``jupyterlite_contents``) The name
+  of a folder where the built Jupyter notebooks will be copied, relative to the
+  Sphinx source directory. This is used as Jupyterlite contents.
+
+You can set variables in ``conf.py`` to configure ``jupyterlite-sphinx``, see
+its `jupyterlite-sphinx doc
+<https://jupyterlite-sphinx.readthedocs.io/en/latest/configuration.html>`__ for
+more details.
+
+If a Sphinx-Gallery configuration for JupyterLite is discovered, the following
+extra things will happen:
+
+1. Configure ``jupyterlite-sphinx`` with some reasonable defaults, e.g. set
+   ``jupyterlite_bind_ipynb_suffix = False``.
+2. The built Jupyter Notebooks from the documentation will be copied to a
+   folder called ``<jupyterlite_contents>/`` (relative to Sphinx source
+   directory)
+3. The rST output of each Sphinx-Gallery example will now have a
+   ``launch JupyterLite`` button in it.
+4. That button will point to a JupyterLite link which will start a Jupyter
+   server in your browser with the current example as notebook
+
+If, for some reason, you want to enable the ``jupyterlite-sphinx`` extension
+but not use sphinx-gallery Jupyterlite integration you can do::
+
+    extensions = [
+        ...,
+        jupyterlite_sphinx,
+    ]
+
+    sphinx_gallery_conf = {
+      ...
+      'jupyterlite': None
+    }
+
+See the Sphinx-Gallery `Sphinx configuration file
+<https://github.com/sphinx-gallery/sphinx-gallery/blob/master/doc/conf.py>`_
+for an example that uses the JupyterLite integration.
+
 .. _promote_jupyter_magic:
 
 Making cell magic executable in notebooks

diff --git a/doc/reference.rst b/doc/reference.rst
@@ -32,7 +32,7 @@ Sphinx-Gallery API Reference
    notebook
    downloads
    sorting
-   binder
+   interactive_example
    directives
 
 .. currentmodule:: sphinx_gallery.utils

diff --git a/setup.py b/setup.py
@@ -42,7 +42,8 @@
         '_static/sg_gallery*.css',
         '_static/no_image.png',
         '_static/broken_example.png',
-        '_static/binder_badge_logo.svg'
+        '_static/binder_badge_logo.svg',
+        '_static/jupyterlite_badge_logo.svg'
     ]},
     scripts=['bin/copy_sphinxgallery.sh', 'bin/sphx_glr_python_to_jupyter.py'],
     url="https://sphinx-gallery.github.io",

diff --git a/sphinx_gallery/_static/jupyterlite_badge_logo.svg b/sphinx_gallery/_static/jupyterlite_badge_logo.svg
diff --git a/sphinx_gallery/_static/sg_gallery-binder.css b/sphinx_gallery/_static/sg_gallery-binder.css
@@ -4,3 +4,8 @@ div.binder-badge {
   margin: 1em auto;
   vertical-align: middle;
 }
+
+div.lite-badge {
+  margin: 1em auto;
+  vertical-align: middle;
+}
diff --git a/sphinx_gallery/downloads.py b/sphinx_gallery/downloads.py
@@ -22,6 +22,8 @@
   .. container:: sphx-glr-footer sphx-glr-footer-example
 
 {2}
+
+{4}
     .. container:: sphx-glr-download sphx-glr-download-python
 
       :download:`Download Python source code: {0} <{0}>`

diff --git a/sphinx_gallery/gen_gallery.py b/sphinx_gallery/gen_gallery.py
@@ -33,10 +33,14 @@
 from .docs_resolv import embed_code_links
 from .downloads import generate_zipfiles
 from .sorting import NumberOfCodeLinesSortKey
-from .binder import copy_binder_files, check_binder_conf
+from .interactive_example import (
+    copy_binder_files, check_binder_conf, check_jupyterlite_conf
+)
+from .interactive_example import pre_configure_jupyterlite_sphinx
+from .interactive_example import post_configure_jupyterlite_sphinx
+from .interactive_example import create_jupyterlite_contents
 from .directives import MiniGallery, ImageSg, imagesg_addnode
 
-
 _KNOWN_CSS = ('sg_gallery', 'sg_gallery-binder', 'sg_gallery-dataframe',
               'sg_gallery-rendered-html')
 
@@ -80,6 +84,7 @@ def __call__(self, gallery_conf, script_vars):
     'thumbnail_size': (400, 280),  # Default CSS does 0.4 scaling (160, 112)
     'min_reported_time': 0,
     'binder': {},
+    'jupyterlite': {},
     'promote_jupyter_magic': False,
     'image_scrapers': ('matplotlib',),
     'compress_images': (),
@@ -371,6 +376,11 @@ def call_memory(func):
     # binder
     gallery_conf['binder'] = check_binder_conf(gallery_conf['binder'])
 
+    # jupyterlite
+    print('_complete_gallery_conf', gallery_conf.get('jupyterlite'))
+    gallery_conf['jupyterlite'] = check_jupyterlite_conf(
+        gallery_conf.get('jupyterlite', {}), app)
+
     if not isinstance(gallery_conf['css'], (list, tuple)):
         raise ConfigError('gallery_conf["css"] must be list or tuple, got %r'
                           % (gallery_conf['css'],))
@@ -1155,6 +1165,15 @@ def setup(app):
     for key in ['plot_gallery', 'abort_on_example_error']:
         app.add_config_value(key, get_default_config_value(key), 'html')
 
+    # set small priority value, so that pre_configure_jupyterlite_sphinx is
+    # called before jupyterlite_sphinx config-inited
+    app.connect(
+        'config-inited', pre_configure_jupyterlite_sphinx, priority=100)
+    # set high priority value, so that post_configure_jupyterlite_sphinx is
+    # called after jupyterlite_sphinx config-inited
+    app.connect(
+        'config-inited', post_configure_jupyterlite_sphinx, priority=900)
+
     if 'sphinx.ext.autodoc' in app.extensions:
         app.connect('autodoc-process-docstring', touch_empty_backreferences)
         app.connect('autodoc-process-docstring', write_api_entries)
@@ -1168,6 +1187,8 @@ def setup(app):
 
     app.connect('builder-inited', generate_gallery_rst)
     app.connect('build-finished', copy_binder_files)
+    app.connect('build-finished', create_jupyterlite_contents)
+
     app.connect('build-finished', summarize_failing_examples)
     app.connect('build-finished', embed_code_links)
     app.connect('build-finished', clean_files)
-Original file line number
+Diff line change
@@ Expand Up / @@ -22,6 +22,8 @@ @@
       .. container:: sphx-glr-footer sphx-glr-footer-example
     {2}
+    {4}
         .. container:: sphx-glr-download sphx-glr-download-python
           :download:`Download Python source code: {0} <{0}>`
@@ Expand Down @@