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.** + + 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 `__ live shell with ``pandas``, powered by `Pyodide `__. + +**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.