ENH, DOC: Add JupyterLite-powered interactive examples for the pandas documentation

.github/workflows/docbuild-and-upload.yml

@@ -59,10 +59,6 @@ jobs:
     - name: Build documentation
       run: doc/make.py --warnings-are-errors
 
-    - name: Build the interactive terminal
-      working-directory: web/interactive_terminal
-      run: jupyter lite build
-
     - name: Build documentation zip
       run: doc/make.py zip_html
 

.gitignore

@@ -122,6 +122,7 @@ test-data.xml
 # Documentation generated files #
 #################################
 doc/source/generated
+/doc/source/_contents
 doc/source/user_guide/styled.xlsx
 doc/source/reference/api
 doc/source/_static/*.html

doc/source/_static/css/pandas.css

@@ -50,3 +50,70 @@ table {
 .card, .card img {
   background-color: var(--pst-color-background);
 }
+
+/* Buttons for JupyterLite-enabled interactive examples */
+/* adapted from https://github.com/numpy/numpy/pull/26745 */
+
+.try_examples_button {
+  position: relative;
+  overflow: hidden;
+  color: white;
+  background-color: var(--pst-color-info);
+  border: none;
+  padding: 5px 10px;
+  border-radius: 0.25rem;
+  margin-top: 3px;  /* better alignment under admonitions */
+  margin-bottom: 5px !important; /* fix uneven button sizes under admonitions */
+  box-shadow: 0 2px 5px rgba(108, 108, 108, 0.2);
+  font-weight: bold;
+  font-size: small;
+}
+
+/* Use more acccessible colours for text in dark mode */
+[data-theme=dark] .try_examples_button {
+  color: black;
+}
+
+.try_examples_button:after {
+  content: '';
+  position: absolute;
+  top: -50%;
+  right: -50%;
+  bottom: -50%;
+  left: -50%;
+  background: linear-gradient(to bottom, rgba(229, 172, 142, 0), rgba(255,255,255,0.5) 50%, rgba(229, 172, 142, 0));
+  transform: rotateZ(-60deg) translate(-12em, -5em); /* Starting from the left */
+}
+
+/* Activate sheen effect on hover */
+.try_examples_button:hover::after {
+  animation: jupyterSheen 1s forwards;
+}
+
+@keyframes jupyterSheen {
+  100% {
+    transform: rotateZ(-60deg) translate(12em, 10em);
+  }
+}
+
+.try_examples_button:hover {
+  transform: scale(1.02);
+  box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
+  cursor: pointer;
+}
+
+.try_examples_button:focus {
+  outline: 0;
+}
+
+.try_examples_button_container {
+  display: flex;
+  justify-content: flex-start;
+  gap: 10px;
+  margin-bottom: 20px;
+}
+
+/* Better gaps for examples buttons under admonitions */
+.try_examples_outer_iframe {
+  margin-top: 0.4em;
+}

doc/source/conf.py

@@ -58,6 +58,7 @@
     "numpydoc",
     "sphinx_copybutton",
     "sphinx_design",
+    "jupyterlite_sphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -420,6 +421,25 @@
 
 nbsphinx_allow_errors = True
 
+# -- Options for jupyterlite-sphinx --------------------------------------
+
+jupyterlite_bind_ipynb_suffix = False
+
+# Configuration for interactive documentation using jupyterlite-sphinx and
+# Pyodide. See https://jupyterlite-sphinx.readthedocs.io/en/stable/ for
+# more options.
+
+global_enable_try_examples = True
+try_examples_global_button_text = "Try it!"
+try_examples_global_warning_text = (
+    "Interactive examples for pandas are experimental and may not always "
+    "work as expected. If you encounter any issues or wish to provide any "
+    "feedback, please reach out to us on the "
+    "[pandas issue tracker](https://github.com/pandas-dev/pandas/issues/new)."
+)
+# uncomment to ease debugging
+# jupyterlite_silence = False
+
 # -- Options for LaTeX output --------------------------------------------
 
 latex_elements = {}

doc/source/getting_started/index.rst

@@ -657,6 +657,28 @@ The community produces a wide variety of tutorials available online. Some of the
 material is enlisted in the community contributed :ref:`communitytutorials`.
 
 
+Try pandas online (experimental)
+--------------------------------
+
+Try our experimental `JupyterLite <https://jupyterlite.readthedocs.io/en/stable/>`__ live shell with ``pandas``, powered by `Pyodide <https://pyodide.org/en/stable/>`__.
+
+**Please note it can take a while (>30 seconds) before the shell is initialized and ready to run commands.**
+
+**Running it requires a reasonable amount of bandwidth and resources (>70 MiB on the first load), so
+it may not work properly on all devices or networks.**
+
+
+.. replite::
+  :kernel: pyodide
+  :height: 600px
+  :prompt: Try pandas online!
+  :execute: False
+  :prompt_color: #E70288
+
+  import pandas as pd
+  df = pd.DataFrame({"num_legs": [2, 4], "num_wings": [2, 0]}, index=["falcon", "dog"])
+  df
+
 .. If you update this toctree, also update the manual toctree in the
    main index.rst.template
 

web/interactive_terminal/jupyter-lite.json → doc/source/jupyter-lite.json

@@ -1,8 +1,7 @@
 {
   "jupyter-lite-schema-version": 0,
   "jupyter-config-data": {
-    "appName": "Pandas REPL",
-    "appUrl": "./repl",
+    "appName": "Pandas JupyterLite deployment",
     "enableMemoryStorage": true,
     "settingsStorageDrivers": ["memoryStorageDriver"],
     "contentsStorageDrivers": ["memoryStorageDriver"]

web/interactive_terminal/jupyter_lite_config.json → doc/source/jupyter_lite_config.json

@@ -1,8 +1,6 @@
 {
   "LiteBuildConfig": {
-    "apps": ["repl"],
     "no_unused_shared_packages": true,
-    "output_dir": "../build/lite",
     "no_sourcemaps": true
   }
 }

doc/source/try_examples.json

@@ -0,0 +1,3 @@
+{
+  "global_min_height": "600px"
+}

environment.yml

@@ -107,6 +107,9 @@ dependencies:
   - nbformat
   - notebook>=7.0.6
   - ipykernel
+  # also listed below
+  - jupyterlite-sphinx
+  - jupyterlite-pyodide-kernel
 
   # web
   # - jinja2  # already listed in optional dependencies, but documented here for reference
@@ -116,11 +119,13 @@ dependencies:
   - requests
   - pygments # Code highlighting
 
-  # web interactive REPL
+  # web interactive REPL and interactive documentation utilities,
+  # already listed above, but documented here for reference.
+  #
   # see the following links for more context:
   # 1. https://jupyterlite-pyodide-kernel.readthedocs.io/en/stable/#compatibility
   # 2. https://pyodide.org/en/stable/usage/packages-in-pyodide.html
-  - jupyterlite-core
+  - jupyterlite-sphinx
   - jupyterlite-pyodide-kernel
 
   - pip:

pandas/_libs/tslibs/offsets.pyx

@@ -5109,7 +5109,7 @@ def _warn_about_deprecated_aliases(name: str, is_period: bool) -> str:
             f"\'{name}\' is deprecated and will be removed "
             f"in a future version, please use "
             f"\'{c_PERIOD_AND_OFFSET_DEPR_FREQSTR.get(name)}\'"
-            f" instead.",
+            f"instead. ",
             FutureWarning,
             stacklevel=find_stack_level(),
             )
@@ -5123,7 +5123,7 @@ def _warn_about_deprecated_aliases(name: str, is_period: bool) -> str:
                 f"\'{name}\' is deprecated and will be removed "
                 f"in a future version, please use "
                 f"\'{_name}\'"
-                f" instead.",
+                f"instead. ",
                 FutureWarning,
                 stacklevel=find_stack_level(),
                 )

requirements-dev.txt

@@ -80,12 +80,14 @@ ipywidgets
 nbformat
 notebook>=7.0.6
 ipykernel
+jupyterlite-sphinx
+jupyterlite-pyodide-kernel
 markdown
 feedparser
 pyyaml
 requests
 pygments
-jupyterlite-core
+jupyterlite-sphinx
 jupyterlite-pyodide-kernel
 adbc-driver-postgresql>=0.10.0
 adbc-driver-sqlite>=0.8.0

web/interactive_terminal/README.md

@@ -6,33 +6,24 @@ An interactive REPL to easily try `pandas` in the browser, powered by JupyterLit
 
 ## Build
 
-The interactive REPL is built with the `jupyter lite` CLI.
-
-First make sure `jupyterlite` and a kernel are installed:
-
-```bash
-python -m pip install jupyterlite-core
-python -m pip install jupyterlite-pyodide-kernel
-```
-
-Then in `web/interactive_terminal`, run the following command:
-
-```bash
-jupyter lite build
-```
+The interactive REPL can be as a part of the documentation build process
+with Sphinx using the `jupyterlite-sphinx` extension. Please refer to the
+`doc/make.py` file and the [pandas docs development workflow](https://pandas.pydata.org/docs/development/contributing_documentation.html#how-to-build-the-pandas-documentation) for more information.
 
 ## Configuration
 
-This folder contains configuration files for the interactive terminal powered by JupyterLite:
+The `doc/source/` folder contains shared configuration files for the interactive terminal powered by JupyterLite:
 
 - `jupyter_lite_config.json`: build time configuration, used when building the assets with the `jupyter lite build` command
 - `jupyter-lite.json` run time configuration applied when launching the application in the browser
 
-This interactive `pandas` JupyterLite deployment enables a couple of optimizations to only include the `repl` app in the generated static assets, and disables source maps, which can make the assets smaller and faster to load, at the cost of
-debugging capabilities.
+This interactive `pandas` JupyterLite deployment enables optimizations by removing unused shared packages
+and disabling source maps, which can make the assets smaller and faster to load, at the cost of debugging
+capabilities.
 
 To learn more about it, check out the JupyterLite documentation:
 
 - Optimizations: https://jupyterlite.readthedocs.io/en/latest/howto/configure/advanced/optimizations.html
 - JupyterLite schema: https://jupyterlite.readthedocs.io/en/latest/reference/schema-v0.html
-- CLI reference: https://jupyterlite.readthedocs.io/en/latest/reference/cli.html
+- `jupyterlite-sphinx` extension: https://jupyterlite-sphinx.readthedocs.io/en/stable/
+- `jupyter lite` CLI reference: https://jupyterlite.readthedocs.io/en/latest/reference/cli.html

web/pandas/try.md

@@ -6,7 +6,12 @@ Try our experimental [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/
 
 **Running it requires a reasonable amount of bandwidth and resources (>70 MiB on the first load), so it may not work properly on all devices or networks.**
 
+<!-- This JupyterLite deployment is reused from the one built using the `jupyterlite-sphinx` Sphinx extension
+as a part of the interactive docs utilities in the pandas documentation.
+
+To debug locally, replace the URL substring below with "../doc/build/html/lite/<...>", as appropriate. -->
+
 <iframe
-  src="./lite/repl/index.html?toolbar=1&kernel=python&execute=0&code=import%20pandas%20as%20pd%0Adf%20%3D%20pd.DataFrame%28%7B%22num_legs%22%3A%20%5B2%2C%204%5D%2C%20%22num_wings%22%3A%20%5B2%2C%200%5D%7D%2C%20index%3D%5B%22falcon%22%2C%20%22dog%22%5D%29%0Adf"
+  src="./docs/lite/repl/index.html?toolbar=1&kernel=python&execute=0&code=import%20pandas%20as%20pd%0Adf%20%3D%20pd.DataFrame%28%7B%22num_legs%22%3A%20%5B2%2C%204%5D%2C%20%22num_wings%22%3A%20%5B2%2C%200%5D%7D%2C%20index%3D%5B%22falcon%22%2C%20%22dog%22%5D%29%0Adf"
   style="width: 100%; max-width: 650px; height: 600px; border: 1px solid #130753;"
 ></iframe>