Add projects' interactive documentation

[trallard]

📝 Summary

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

🚀 Tasks / Deliverables

TBD

📅 Estimated completion

24 months milestone

📋 Additional information

Status

This table is best complemented by the one in https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/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 https://github.com/pyodide/pyodide/issues/4898. For discussions predating this choice where thoughts pertaining to an ideal location for nightly wheels were being exchanged, please refer to https://github.com/pyodide/pyodide/issues/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 wheels in deployments
NumPy	✅ Both	🚀 Docstring-based API examples (where applicable) are ready at https://github.com/numpy/numpy/pull/26745. "User Guide" section awaits design decisions. The NumPy tutorials website is not ready yet.	Nightly wheels available but not used, hoping to use https://github.com/pyodide/pyodide/pull/4925 when released or to let micropip use nightly wheels
PyWavelets	✅ Both	Examples under "API Reference" were enabled for interactivity via https://github.com/PyWavelets/pywt/pull/728. https://github.com/PyWavelets/pywt/pull/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 https://github.com/PyWavelets/pywt/issues/777.	Planned, nightly wheels available
pandas	✅ Both	Planned	Planned, nightly wheels available
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 and JupyterLite	Not yet – the current stable release is 1.5.2 and 1.4.2 is being used for the notebooks
scikit-image	✅ Both	Planned	Planned, nightly wheels available
statsmodels	✅ Both	Planned, MkDocs is used instead of Sphinx, so either an alternative extension to enable JupyterLite would be needed, or a JupyterLite distribution hosted separately that opens in a new tab	Planned, nightly wheels available
Zarr	WASM builds in progress. Updated versions of all dependencies are now available in Pyodide in-tree, awaiting Pyodide 0.27 release	Planned	Planned
numcodecs	WASM builds are ready for review	❌ Not planned, since numcodecs is not particularly user-facing and is not a major dependency for Zarr's codecs	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 https://github.com/pyodide/pyodide/issues/5030 to cross-compile F77/F90 code to WASM directly instead of f2c, needs experimentation	Docstring-based API examples deployed https://github.com/scipy/scipy/pull/20019, later disabled and need to be re-enabled. scipy.stats notebooks were deployed in https://github.com/scipy/scipy/pull/20303 and https://github.com/scipy/scipy/pull/21042 in a similar fashion to PyWavelets's above – via Jupytext for documentation build-time conversion from reST to MyST format	Planned, nightly wheels available
SymPy	✅ Both	Available. Documentation is built with Furo theme instead of PST, some aesthetic changes to jupyterlite-sphinx might be needed.	Nightly wheels available, and are planned for use in SymPy's live shell first before proceeding to SymPy tutorials.
Matplotlib	Out-of-tree builds tracked in https://github.com/matplotlib/matplotlib/issues/27870, being tracked in https://github.com/matplotlib/matplotlib/pull/29093. Builds available in-tree, though outdated	Planned, needs Pyodide 0.27 stable release and possibly a few further bumps to match upstream	Planned for addition in https://github.com/matplotlib/matplotlib/pull/29093
h5py and libhdf5	https://github.com/h5py/h5py/issues/2397	Planned, decision needed	Planned
PyTables	Planned, decision needed	Planned, decision needed	Planned

[rgommers]

Year 1 goal of the first interactive docs for 1 project (SciPy) almost met, see gh-16.

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

[rgommers]

As a quick update:

• a lot of work was done on https://github.com/jupyterlite/jupyterlite-sphinx to make the user experience for interactive docs polished
• https://pywavelets.readthedocs.io/en/latest/ is deployed and contains buttons with each example in the reference guide to start JupyterLite and try things interactively
• the SciPy infra is all there, the switch just needs to be flipped now that SciPy 0.12.0 is becoming available in Pyodide 0.26.0 (not yet up on PyPI, but expected very soon).

[rgommers]

Also related: a fair amount of work is going into making binary wheels smaller (e.g. the machinery to strip off tests and data with a single build flag), reducing the number of build variants in compiled code, etc. Small binaries will be quite important to make the user experience good, because downloading many MBs of packages yields high latency and can be costly when a user doesn't have a connection with unlimited bandwidth.

[rgommers]

@agriyakhetarpal it may be useful to have a Status table in the issue description here (just like in gh-18), linking to deployed interactive docs and/or open PRs. Would you be able to create one?

[agriyakhetarpal]

Yes, I'll do this in a moment, @rgommers. I expect that my interactive docs work will increase in magnitude in the coming months.