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/.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 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; +} diff --git a/doc/source/conf.py b/doc/source/conf.py index 677ee6274b093..b07a6ab6cc97f 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,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 = {} 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 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"] 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 } } 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" +} 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/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 990901958cd9e..56a9764055e62 100644 --- a/requirements-dev.txt +++ b/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 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.** + +