Add projects' interactive documentation

[trallard]

📝 Summary

Expand the availability of interactive documentation examples and tutorials to at least five projects.

🚀 Tasks / Deliverables

See the "Status" section below

📅 Estimated completion

24 months milestone

📋 Additional information

Status

Interactive documentation websites for projects: insights

This table is best complemented by the one in #18 which contains further linked PRs about out-of-tree Pyodide/WASM CI builds (first column here) and around PRs linked towards the availability of nightly wheels (third column here). The nightly wheels for projects have been hosted on the Anaconda.org PyPI index at https://anaconda.org/scientific-python-nightly-wheels. For the lack of CORS headers around the installation of nightly wheels, please refer to pyodide/pyodide#4898. For discussions predating this choice where thoughts pertaining to an ideal location for nightly wheels were being exchanged, please refer to pyodide/pyodide#3049.

Package name	🧱 Builds for WASM (either out-of-tree CI builds, in-tree within the Pyodide distribution, or both)	🚀 Interactive documentation deployments	🌃 Use of nightly WASM wheels in deployments
NumPy	✅ Both	🚀 Docstring-based API examples (where applicable) merged at numpy/numpy#26745 and available on the "latest" documentation at https://numpy.org/devdocs/reference/. They will be available in the stable release with NumPy 2.3.0: https://numpy.org/devdocs/release/2.3.0-notes.html#interactive-examples-in-the-numpy-documentation; NumPy 2.3 maintenance branch cut hasn't happened yet. The "User Guide" section is being converted and awaits design decisions. The NumPy tutorials website is not ready yet.	Nightly WASM wheels are available but have not yet been utilised.
PyWavelets	✅ Both	Examples under "API Reference" were enabled for interactivity via PyWavelets/pywt#728. PyWavelets/pywt#741 aims to convert the "Usage examples" section with long-form notebook-based content. There are some discussions around switching to GitHub Pages (to be finalised) at PyWavelets/pywt#777.	Planned, and nightly wheels available but not used yet
pandas	✅ Both	In progress. pandas-dev/pandas#60758 was merged, and is being followed with pandas-dev/pandas#61061	Planned, nightly wheels available but not used yet
awkward and awkward-cpp	CI builds for WASM in out-of-tree are enabled with a docs-based workflow, though not fully tested via the test suite. In-tree builds available with Pyodide releases	An interactive shell is available at https://awkward-array.org/doc/main/_static/try-it.html which preloads Awkward Array for importing – does not use jupyterlite-sphinx yet	Extra wheels left in with Pyodide distribution using JupyterLite. Nightly wheels are not hosted on Anaconda.org or used
scikit-learn	✅ Both	✅ Yes, deployed using Sphinx-Gallery's JupyterLite integration already	✅ scikit-learn/scikit-learn#31085
scikit-image	✅ Both	scikit-image/scikit-image#7644 attempts to add interactive examples	Awaiting a review in scikit-image/scikit-image#7440
statsmodels	✅ Both	Uses sphinx-immaterial – styling differences exist with PST and aesthetic changes will be required for the buttons. In progress at statsmodels/statsmodels#9536	Planned, nightly wheels available but not used yet
Zarr	WASM builds in progress. Updated versions of all dependencies are now available in Pyodide in-tree with Pyodide 0.27	Planned	Planned
numcodecs	WASM builds completed via zarr-developers/numcodecs#529, awaiting a review	❌ Not planned, since numcodecs is not particularly user-facing and is not a major dependency for Zarr's codecs	❌ Not planned
SciPy	In-tree builds up-to-date in Pyodide 0.27 alpha releases. Out-of-tree CI job not implemented yet because of magnitude of FORTRAN 77 patches. Possibility to use flang via LLVM 19 via pyodide/pyodide-recipes#238 to cross-compile F77/F90 code to WASM directly instead of f2c, needs experimentation	Docstring-based API examples deployed scipy/scipy#20019, later disabled and need to be re-enabled – tracked in scipy/scipy#22241 and being looked into. The scipy.stats notebooks were deployed for a start in in scipy/scipy#20303 and scipy/scipy#21042 in a similar fashion to PyWavelets's above – via Jupytext for documentation build-time conversion from reST to MyST Markdown notebooks	Planned
SymPy	✅ Both	Documentation is built with Furo theme instead of PST, some aesthetic changes to jupyterlite-sphinx's style applied via sympy/sympy#27419, awaiting merge. Additional context: interactive doctest-based examples used to exist with a server-side Google App Engine deployment and a Sphinx extension, but have been long deprecated.	Nightly wheels are available, and are planned for use in SymPy's live shell first before proceeding to SymPy tutorials. Update as of 03/01/2025: via sympy/live#22, https://live.sympy.org is now at the latest available stable version at the time of writing. Update as of 21/01/2025: nightly wheels will be used post merge of SymPy docs interactivity PR noted above.
Matplotlib	Out-of-tree builds tracked in matplotlib/matplotlib#27870, being tracked in matplotlib/matplotlib#29093. Builds available in-tree up to version 3.8.4 via pyodide/pyodide#4510, and patched WebAgg planned for further use (see pyodide/pyodide#5398 and matplotlib/matplotlib#29568)	In progress at matplotlib/matplotlib#29506 which adds a shell and enables the gallery, Sphinx-Gallery's JupyterLite integration planned next	Planned for addition in matplotlib/matplotlib#29093
h5py and libhdf5	h5py/h5py#2397	Planned, decision needed	Planned
PyTables	Planned, decision needed	Planned, decision needed	Planned

Miscellaneous items of note

Installation of nightly wheels for projects' "dev"/"latest" docs websites

• CORS headers now available for Anaconda.org via Web proxy to work around the lack of CORS headers for nightly wheels uploaded to the Anaconda.org index pyodide/pyodide#4898 as of 06/02/2025, eliminating use of proxy

• an --index-urls CLI command for piplite is in progress at Add a --index-urls CLI flag for pip-install magics jupyterlite/pyodide-kernel#166
• Extra indices for lookup in addition to Pyodide CDN and PyPI (and local) is in progress at Allow to install extra packages from extra indexes from jupyter-lite.json jupyterlite/pyodide-kernel#158

Communication and adoption

See pyodide/pyodide#17 for interactive docs SPEC – first draft by @agriyakhetarpal ready as of 04/03/2025 and undergoing internal review(s)

Notebook styling improvements for docs

See pyodide/pyodide#142 for the major round-up around design decisions for notebook-based docs.

• Gist: DOC: Add interactive notebooks to pages in the "Usage Examples" section PyWavelets/pywt#741 added better notebook input/output styling, with upstreaming and standardisation to take place in the PyData Sphinx Theme and notebook collaborators.

• Super compact error for docs tracebacks ipython/ipython#14591 addressed via Create a new xmode "Docs" ipython/ipython#14752, brings as small a traceback as possible for docs; awaits Python 9.0 release for usage.

[rgommers]

Year 1 goal of the first interactive docs for 1 project (SciPy) almost met, see pyodide/pyodide#16.

@Carreau is now joining in to work on this larger year 2 goal.