From 906d8572ef36b89749d316c759ba6baca5703590 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 22:58:26 +0530
Subject: [PATCH 01/12] Move runtime configuration to `doc/source/`
---
{web/interactive_terminal => doc/source}/jupyter-lite.json | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
rename {web/interactive_terminal => doc/source}/jupyter-lite.json (79%)
diff --git a/web/interactive_terminal/jupyter-lite.json b/doc/source/jupyter-lite.json
similarity index 79%
rename from web/interactive_terminal/jupyter-lite.json
rename to doc/source/jupyter-lite.json
index 2199acf1d368a..639f6c04c07ad 100644
--- a/web/interactive_terminal/jupyter-lite.json
+++ b/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"]
From d1ef0fcc74d724782d1fabb1844c4acd64d15bd9 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 22:58:40 +0530
Subject: [PATCH 02/12] Move build-time configuration to `doc/source/`
---
.../source}/jupyter_lite_config.json | 2 --
1 file changed, 2 deletions(-)
rename {web/interactive_terminal => doc/source}/jupyter_lite_config.json (62%)
diff --git a/web/interactive_terminal/jupyter_lite_config.json b/doc/source/jupyter_lite_config.json
similarity index 62%
rename from web/interactive_terminal/jupyter_lite_config.json
rename to doc/source/jupyter_lite_config.json
index 42e64f26f2356..38bb4cb32ae2a 100644
--- a/web/interactive_terminal/jupyter_lite_config.json
+++ b/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
}
}
From 3e09e1a10054cf926bd0ccd67e39287da282bd73 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 22:59:54 +0530
Subject: [PATCH 03/12] Add `jupyterlite-sphinx` as a dependency
---
environment.yml | 9 +++++++--
requirements-dev.txt | 2 +-
2 files changed, 8 insertions(+), 3 deletions(-)
diff --git a/environment.yml b/environment.yml
index a8c8b20e20fe4..4f641753579bc 100644
--- a/environment.yml
+++ b/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:
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 990901958cd9e..67a6b38b552a9 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -85,7 +85,7 @@ feedparser
pyyaml
requests
pygments
-jupyterlite-core
+jupyterlite-sphinx
jupyterlite-pyodide-kernel
adbc-driver-postgresql>=0.10.0
adbc-driver-sqlite>=0.8.0
From e960a3ab313afb328810bf27592891fa5ffecee8 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:00:08 +0530
Subject: [PATCH 04/12] Condigure `jupyterlite_sphinx`
---
doc/source/conf.py | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 677ee6274b093..76d41aacfdb8f 100644
--- a/doc/source/conf.py
+++ b/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,23 @@
nbsphinx_allow_errors = True
+# -- Options for jupyterlite-sphinx --------------------------------------
+
+# 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 = {}
From df33314732a1a84f50317b9c4cda13ffb3d04ee5 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:00:32 +0530
Subject: [PATCH 05/12] Ignore generated contents by `TryExamples`
---
.gitignore | 1 +
1 file changed, 1 insertion(+)
diff --git a/.gitignore b/.gitignore
index d951f3fb9cbad..5cc7dcff69a06 100644
--- a/.gitignore
+++ b/.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
From ebcb57c2d0a7003d4f19c6fa1f24cb073ade381c Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:00:50 +0530
Subject: [PATCH 06/12] Enforce proper rendering of `TryExamples` notebooks
---
doc/source/try_examples.json | 3 +++
1 file changed, 3 insertions(+)
create mode 100644 doc/source/try_examples.json
diff --git a/doc/source/try_examples.json b/doc/source/try_examples.json
new file mode 100644
index 0000000000000..5e7e13e9b69cb
--- /dev/null
+++ b/doc/source/try_examples.json
@@ -0,0 +1,3 @@
+{
+ "global_min_height": "600px"
+}
From 20e4d5521d28a7826d7f8a891241235176d93871 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:03:50 +0530
Subject: [PATCH 07/12] Don't build the interactive terminal separately
---
.github/workflows/docbuild-and-upload.yml | 4 ----
web/interactive_terminal/README.md | 27 ++++++++---------------
web/pandas/try.md | 7 +++++-
3 files changed, 15 insertions(+), 23 deletions(-)
diff --git a/.github/workflows/docbuild-and-upload.yml b/.github/workflows/docbuild-and-upload.yml
index 294334ca1d54b..908baa87815ab 100644
--- a/.github/workflows/docbuild-and-upload.yml
+++ b/.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
diff --git a/web/interactive_terminal/README.md b/web/interactive_terminal/README.md
index 6457cbccf2016..75b3a35b877ab 100644
--- a/web/interactive_terminal/README.md
+++ b/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
diff --git a/web/pandas/try.md b/web/pandas/try.md
index ee2f98b05aa64..d3d23b1ff5246 100644
--- a/web/pandas/try.md
+++ b/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>
From 1e9366d17bc69b448a23a7a4edf2f5360e6e072f Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:04:22 +0530
Subject: [PATCH 08/12] Add some styling for the `TryExamples` buttons
---
doc/source/_static/css/pandas.css | 67 +++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
diff --git a/doc/source/_static/css/pandas.css b/doc/source/_static/css/pandas.css
index 1145177898737..fe810f3214916 100644
--- a/doc/source/_static/css/pandas.css
+++ b/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;
+}
From 741ca1b4da9acc3d7b2fdea0577b631c95d6e01a Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 5 Mar 2025 23:28:05 +0530
Subject: [PATCH 09/12] Add REPL to the Getting Started page
---
doc/source/getting_started/index.rst | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst
index a17699a71fbd3..019a6b8514917 100644
--- a/doc/source/getting_started/index.rst
+++ b/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
From 5c3e805ea7d16cd42af03c67641d4bb49329cd4e Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Thu, 6 Mar 2025 00:58:49 +0530
Subject: [PATCH 10/12] Fix pre-commit failures
---
pandas/_libs/tslibs/offsets.pyx | 4 ++--
requirements-dev.txt | 2 ++
2 files changed, 4 insertions(+), 2 deletions(-)
diff --git a/pandas/_libs/tslibs/offsets.pyx b/pandas/_libs/tslibs/offsets.pyx
index a16964435ef50..9858a6f0759b4 100644
--- a/pandas/_libs/tslibs/offsets.pyx
+++ b/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(),
)
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 67a6b38b552a9..56a9764055e62 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -80,6 +80,8 @@ ipywidgets
nbformat
notebook>=7.0.6
ipykernel
+jupyterlite-sphinx
+jupyterlite-pyodide-kernel
markdown
feedparser
pyyaml
From 00cac61e2bdb68367cef3fdfed306399f438150e Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Thu, 6 Mar 2025 00:59:24 +0530
Subject: [PATCH 11/12] Silence JupyterLite again
---
doc/source/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 76d41aacfdb8f..8154bc7ef1341 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -436,7 +436,7 @@
"[pandas issue tracker](https://github.com/pandas-dev/pandas/issues/new)."
)
# uncomment to ease debugging
-jupyterlite_silence = False
+# jupyterlite_silence = False
# -- Options for LaTeX output --------------------------------------------
From 1f99439bfd52def9a3584e8429fb64964c85a82b Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Thu, 6 Mar 2025 02:17:08 +0530
Subject: [PATCH 12/12] Fix docs build failures due to warnings
---
doc/source/conf.py | 2 ++
1 file changed, 2 insertions(+)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8154bc7ef1341..b07a6ab6cc97f 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -423,6 +423,8 @@
# -- 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.