Skip to content

Commit 28f744d

Browse files
amuellerlestevelarsonerglemaitre
authored
Jupyterlite integration (#977)
Co-authored-by: Loïc Estève <loic.esteve@ymail.com> Co-authored-by: Eric Larson <larson.eric.d@gmail.com> Co-authored-by: Guillaume Lemaitre <g.lemaitre58@gmail.com>
1 parent 9737931 commit 28f744d

20 files changed

Lines changed: 493 additions & 25 deletions

‎.circleci/config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ jobs:
4141
command: |
4242
pip install --progress-bar off --user --upgrade --only-binary ":all:" pip setuptools
4343
pip install --progress-bar off --user --upgrade --only-binary ":all:" numpy matplotlib "pyqt5!=5.15.2,!=5.15.3,!=5.15.8" vtk
44-
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"
44+
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
4545
pip install --progress-bar off --user --upgrade --pre pydata-sphinx-theme
4646
- save_cache:
4747
key: cache-pip

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,6 @@ target/
8181

8282
# Jupyter notebooks
8383
.ipynb_checkpoints
84+
85+
# Default JupyterLite content
86+
jupyterlite_contents

‎azure-pipelines.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ stages:
6060
pip install --user --upgrade --progress-bar off "ipython!=8.7.0" numpy seaborn statsmodels matplotlib sphinx pillow pytest pytest-cov joblib "plotly>=4.0"
6161
pip install --user --upgrade --progress-bar off --pre pydata-sphinx-theme
6262
echo "Qt, plotly, VTK"
63-
pip install --user --upgrade --progress-bar off pyvista "pyqt5!=5.15.8" plotly vtk
63+
pip install --user --upgrade --progress-bar off pyvista "pyqt5!=5.15.8" plotly vtk jupyterlite-sphinx
6464
echo "Mayavi"
6565
pip install --user --upgrade --progress-bar off --no-build-isolation mayavi
6666
displayName: Setup pip environment

‎continuous_integration/azure/install.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ if [ "$DISTRIB" == "conda" ]; then
1515
echo "##vso[task.prependpath]$CONDA/bin"
1616
export PATH=${CONDA}/bin:${PATH}
1717
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"
18-
PIP_DEPENDENCIES="check-manifest"
18+
PIP_DEPENDENCIES="check-manifest jupyterlite-sphinx"
1919
if [ "$SPHINX_VERSION" == "" ]; then
2020
PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx jinja2<=3.0.3"
2121
elif [ "$SPHINX_VERSION" == "dev" ]; then

‎dev-requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ plotly
1515
absl-py
1616
graphviz
1717
packaging
18+
jupyterlite-sphinx

‎doc/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
'sphinx.ext.mathjax',
4747
'sphinx_gallery.gen_gallery',
4848
'sphinx.ext.graphviz',
49+
'jupyterlite_sphinx',
4950
]
5051

5152
# Add any paths that contain templates here, relative to this directory.

‎doc/configuration.rst‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ file:
5050
- ``show_memory`` (:ref:`show_memory`)
5151
- ``show_signature`` (:ref:`show_signature`)
5252
- ``binder`` (:ref:`binder_links`)
53+
- ``jupyterlite`` (:ref:`jupyterlite`)
5354
- ``promote_jupyter_magic`` (:ref:`promote_jupyter_magic`)
5455
- ``first_notebook_cell`` and ``last_notebook_cell`` (:ref:`own_notebook_cell`)
5556
- ``notebook_images`` (:ref:`notebook_images`)
@@ -1117,6 +1118,108 @@ See the Sphinx-Gallery `Sphinx configuration file
11171118
<https://github.com/sphinx-gallery/sphinx-gallery/blob/master/doc/conf.py>`_
11181119
for an example that uses the `public Binder server <https://mybinder.org>`_.
11191120

1121+
.. _jupyterlite:
1122+
1123+
Generate JupyterLite links for gallery notebooks (experimental)
1124+
===============================================================
1125+
1126+
Sphinx-Gallery automatically generates Jupyter notebooks for any examples built
1127+
with the gallery. `JupyterLite <https://jupyterlite.readthedocs.io>`__ makes it
1128+
possible to run an example in your browser. The functionality is quite similar
1129+
to Binder in the sense that you will get a Jupyter environment where you can
1130+
run the example interactively as a notebook. The main difference with Binder
1131+
are:
1132+
1133+
- with JupyterLite, the example actually runs in your browser, there is no need
1134+
for a separate machine in the cloud to run your Python code. That means that
1135+
starting a Jupyter server is genrally quicker, no need to wait for the Binder
1136+
image to be built
1137+
- with JupyterLite the first imports take time. At the time of writing
1138+
(February 2023) ``import scipy`` can take ~15-30s. Some innocuously looking
1139+
Python code may just not work and break in an unexpected fashion. The Jupyter
1140+
kernel is based on Pyodide, see some `here
1141+
<https://pyodide.org/en/latest/usage/wasm-constraints.html>`__ for some
1142+
Pyodide limitations.
1143+
- with JupyterLite environments are not as flexible as Binder, for example you
1144+
can not use a docker image but only the default `Pyodide
1145+
<https://pyodide.org/en/stable/index.html>`__ environment. That means that
1146+
some non pure-Python packages may not be available, see list of `available
1147+
packages in Pyodide
1148+
<https://pyodide.org/en/stable/usage/packages-in-pyodide.html>`__.
1149+
1150+
.. warning::
1151+
1152+
JupyterLite is still beta technology and less mature than Binder, so there
1153+
may be instability or unexpected behaviour in the experience of users who
1154+
click JupyterLite links.
1155+
1156+
In order to enable JupyterLite links with Sphinx-Gallery, you must install the
1157+
`jupyterlite-sphinx <https://jupyterlite-sphinx.readthedocs.io>`_ package and
1158+
add it to your extensions in ``conf.py``::
1159+
1160+
extensions = [
1161+
...,
1162+
...,
1163+
...,
1164+
'jupyterlite_sphinx',
1165+
]
1166+
1167+
You can configure JupyterLite integration by setting
1168+
``sphinx_gallery_conf['jupyterlite']`` in ``conf.py`` like this::
1169+
1170+
sphinx_gallery_conf = {
1171+
...
1172+
'jupyterlite': {
1173+
'jupyterlite_contents': <str> # JupyterLite contents where to copy the example notebooks (relative to Sphinx source directory)
1174+
'use_jupyter_lab': <bool> # Whether JupyterLite links should start Jupyter Lab instead of the Retrolab Notebook interface.
1175+
}
1176+
}
1177+
1178+
Below is a more complete explanation of each field.
1179+
1180+
use_jupyter_lab (type: bool, default: ``True``)
1181+
Whether the default interface activated by the JupyterLite link will be for
1182+
Jupyter Lab or the RetroLab Notebook interface.
1183+
1184+
jupyterlite_contents (type: string, default: ``jupyterlite_contents``) The name
1185+
of a folder where the built Jupyter notebooks will be copied, relative to the
1186+
Sphinx source directory. This is used as Jupyterlite contents.
1187+
1188+
You can set variables in ``conf.py`` to configure ``jupyterlite-sphinx``, see
1189+
its `jupyterlite-sphinx doc
1190+
<https://jupyterlite-sphinx.readthedocs.io/en/latest/configuration.html>`__ for
1191+
more details.
1192+
1193+
If a Sphinx-Gallery configuration for JupyterLite is discovered, the following
1194+
extra things will happen:
1195+
1196+
1. Configure ``jupyterlite-sphinx`` with some reasonable defaults, e.g. set
1197+
``jupyterlite_bind_ipynb_suffix = False``.
1198+
2. The built Jupyter Notebooks from the documentation will be copied to a
1199+
folder called ``<jupyterlite_contents>/`` (relative to Sphinx source
1200+
directory)
1201+
3. The rST output of each Sphinx-Gallery example will now have a
1202+
``launch JupyterLite`` button in it.
1203+
4. That button will point to a JupyterLite link which will start a Jupyter
1204+
server in your browser with the current example as notebook
1205+
1206+
If, for some reason, you want to enable the ``jupyterlite-sphinx`` extension
1207+
but not use sphinx-gallery Jupyterlite integration you can do::
1208+
1209+
extensions = [
1210+
...,
1211+
jupyterlite_sphinx,
1212+
]
1213+
1214+
sphinx_gallery_conf = {
1215+
...
1216+
'jupyterlite': None
1217+
}
1218+
1219+
See the Sphinx-Gallery `Sphinx configuration file
1220+
<https://github.com/sphinx-gallery/sphinx-gallery/blob/master/doc/conf.py>`_
1221+
for an example that uses the JupyterLite integration.
1222+
11201223
.. _promote_jupyter_magic:
11211224

11221225
Making cell magic executable in notebooks

‎doc/reference.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Sphinx-Gallery API Reference
3232
notebook
3333
downloads
3434
sorting
35-
binder
35+
interactive_example
3636
directives
3737

3838
.. currentmodule:: sphinx_gallery.utils

‎setup.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@
4242
'_static/sg_gallery*.css',
4343
'_static/no_image.png',
4444
'_static/broken_example.png',
45-
'_static/binder_badge_logo.svg'
45+
'_static/binder_badge_logo.svg',
46+
'_static/jupyterlite_badge_logo.svg'
4647
]},
4748
scripts=['bin/copy_sphinxgallery.sh', 'bin/sphx_glr_python_to_jupyter.py'],
4849
url="https://sphinx-gallery.github.io",

‎sphinx_gallery/_static/jupyterlite_badge_logo.svg‎

Lines changed: 3 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)