From 9f04c2fac993293a51470dcf8bf703fc078866da Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 20 May 2023 09:07:03 +0200
Subject: [PATCH] ENH: include jupyterlite in the supported extention (#1023)

* display a jupyterlite output

* simplify the build

* add jupyterlite to the req

* add disclaimer

* split viz libs and execution libs

* Update docs/examples/pydata.md
---
 docs/conf.py                |  1 +
 docs/examples/execution.rst | 38 +++++++++++++++++++++++++++++++++++++
 docs/examples/index.rst     |  1 +
 docs/examples/pydata.md     | 19 +------------------
 pyproject.toml              |  1 +
 5 files changed, 42 insertions(+), 18 deletions(-)
 create mode 100644 docs/examples/execution.rst

diff --git a/docs/conf.py b/docs/conf.py
index aeac8f200..d75c7d4e8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -42,6 +42,7 @@
     # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
     "numpydoc",
     "sphinx_togglebutton",
+    "jupyterlite_sphinx",
     "sphinx_favicon",
 ]
 
diff --git a/docs/examples/execution.rst b/docs/examples/execution.rst
new file mode 100644
index 000000000..3991c9d6e
--- /dev/null
+++ b/docs/examples/execution.rst
@@ -0,0 +1,38 @@
+Execution Libraries
+===================
+
+Many execution libraries can be used to display the output of IPyhton cells. We used ``MySTnb`` to parse and display the outputs presented in :doc:`./pydata`. In this section we'll show alternatives that runs code for you using a Jupyter like kernel.
+
+Jupyterlite
+-----------
+
+.. warning::
+    The jupyterLite lib is not yet providing a handle to switch from light to dark theme. If you consider using it in your documentation you should also enforce the light theme to your users.
+    Follow https://github.com/jupyterlite/jupyterlite-sphinx/issues/69 for more information.
+
+``jupyterlite-sphinx`` brings the power of `JupyterLite <https://jupyterlite.readthedocs.io/en/latest/>`__ to your Sphinx documentation. It makes a full JupyterLite deployment in your docs and provide some utilities for using that deployment easily.
+
+This section demonstrate how it displays in a **pydata-sphinx-theme** context:
+
+.. replite::
+    :kernel: python
+    :height: 600px
+    :prompt: Try Replite!
+
+    print("it's a test")
+
+jupyter-sphinx
+--------------
+
+Another common library is ``jupyter-sphinx``.
+This section demonstrates a subset of functionality to make sure it behaves as expected.
+
+.. jupyter-execute::
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    rng = np.random.default_rng()
+    data = rng.standard_normal((3, 100))
+    fig, ax = plt.subplots()
+    ax.scatter(data[0], data[1], c=data[2], s=3)
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
index 40f92d162..1cf97015b 100644
--- a/docs/examples/index.rst
+++ b/docs/examples/index.rst
@@ -19,6 +19,7 @@ See the sections in the primary sidebar and below to explore.
 
     kitchen-sink/index
     pydata
+    execution
     api
 
 
diff --git a/docs/examples/pydata.md b/docs/examples/pydata.md
index 0c808526d..e31a90905 100644
--- a/docs/examples/pydata.md
+++ b/docs/examples/pydata.md
@@ -3,8 +3,6 @@ file_format: mystnb
 kernelspec:
   name: python3
   display_name: Python 3
-mystnb:
-  execution_mode: cache
 ---
 
 % To test this file with nbsphinx we need to convert to ipynb. To do this:
@@ -97,23 +95,8 @@ data
 
 ```{code-cell}
 from ipyleaflet import Map, basemaps
-from IPython.display import display
 
 # display a map centered on France
 m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])
-display(m)
-```
-
-## jupyter-sphinx
-
-This theme has styling for [`jupyter-sphinx`](https://jupyter-sphinx.readthedocs.io/), which is often used for executing and displaying widgets with a Jupyter kernel.
-
-```{jupyter-execute}
-import matplotlib.pyplot as plt
-import numpy as np
-
-rng = np.random.default_rng()
-data = rng.standard_normal((3, 100))
-fig, ax = plt.subplots()
-ax.scatter(data[0], data[1], c=data[2], s=3)
+m
 ```
diff --git a/pyproject.toml b/pyproject.toml
index bd32ec296..bee28fcdb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,6 +66,7 @@ doc = [
   "sphinx-copybutton",
   "sphinx-design",
   "sphinx-togglebutton",
+  "jupyterlite-sphinx",
   "sphinxcontrib-youtube",
   "sphinx-favicon>=1.0.1",
   # Install nbsphinx in case we want to test it locally even though we can't load