ENH, DOC: Add JupyterLite-powered interactive examples for the pandas documentation
#61061
Conversation
There was a problem hiding this comment.
Here is a self-review where I leave some comments that I decided not to inline in code.
Unfortunately, for the interactive examples to work, the policy listed on the https://pandas.pydata.org/docs/development/contributing_docstring.html#section-7-examples page concerning the non-addition of import pandas as pd or import numpy statements might need to be revisited by the pandas maintainers. This is because jupyterlite-sphinx will convert the examples section to a mini-notebook that will be provided to JupyterLite, and rendered in-place. It is thus imperative for all docstring-based examples to be "self-contained", i.e., be copy-pasteable directly into a terminal or IPython shell where no other programs have been pre-imported.
I performed the same change for numpy/numpy#26814. This was also in discussion over at SciPy in scipy/scipy#13049, where the outcome was to add the necessary imports. I'm curious to know if this can be a possibility here, too.
I'll open this up and mark it ready for review, though it isn't ready for merging.
| 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 | ||
|
|
There was a problem hiding this comment.
Hi @Dr-Irv, this should address #61060 – I've marked this PR as closing the issue.
Specifically, what I've added here is jupyterlite-sphinx's Replite directive, which brings the same interface as the one that now exists on https://pandas.pydata.org/try.html, and both Getting Started pages will use the same JupyterLite live shell, sharing the JupyterLite assets. This directive was designed for this purpose. This shell in the docs, just like the one on the website, does not load or consume any bandwidth until a user explicitly interacts with the REPL button (and goes further by not loading even the JupyterLite assets until prompted).
I can switch this to just a link instead of a REPL, if you wish.
| { | ||
| "global_min_height": "600px" | ||
| } |
There was a problem hiding this comment.
We've documented this option here: https://jupyterlite-sphinx.readthedocs.io/en/latest/directives/try_examples.html#global-min-height
| # 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 |
There was a problem hiding this comment.
jupyterlite-sphinx depends on jupyterlite-core.
|
The remaining CI failures here look unrelated; I merged |
pandasin CI #57896; closes DOC: Add link to the "try pandas online" in the regular documentation #61060doc/source/whatsnew/vX.X.X.rstfile if fixing a bug or adding a new feature.Description
This PR is the first step in a series of PRs to add WASM-based interactive documentation elements for the pandas documentation. Particularly, this relies on JupyterLite and jupyterlite-sphinx.
The interactive REPL added to the website has been incorporated to use the same JupyterLite deployment that
jupyterlite-sphinxinternally builds, so that we don't build a separate/duplicate deployment.The
TryExamplesdirective from jupyterlite-sphinx has been added globally to all Numpydoc-processed docstrings with an "Examples" section via aglobal_enable_try_examplesconfiguration option. The buttons enabled by the directive have been styled accordingly.Next steps
The follow-up steps after this PR will be to:
pandasavailable to use from the Pyodide distribution and the version of pandas that users are viewing the documentation for (most likely when we release Pyodide 0.28)See also
jupyterlite-sphinxnumpy/numpy#26745sphinx-gallery: https://sphinx-gallery.github.io/stable/configuration.html#jupyterliteTryExamplesdirective, used to enable API reference examples: https://jupyterlite-sphinx.readthedocs.io/en/latest/directives/try_examples.html