Interactive documentation for Scientific Python projects

[melissawm]

There are lots of moving parts in the "interactive documentation" space for multiple projects in our ecosystem. I'd like to spend some time documenting the status quo and understanding the challenges in this space.

References

• https://github.com/jupyterlite
• https://github.com/scipy/scipy/pull/20303
• https://pywavelets.readthedocs.io/en/latest/ref/index.html

Please add more as appropriate 😄

[drammock]

this is tangentially related: https://github.com/sphinx-gallery/sphinx-gallery/pull/1312

[steppi]

Thanks for creating this @melissawm. I was planning to post a similar issue today.

[betatim]

Another* example of what is floating around is the example gallery in scikit-learn. Most comes via sphinx gallery (I think)

https://scikit-learn.org/stable/auto_examples/release_highlights/plot_release_highlights_1_4_0.html#sphx-glr-auto-examples-release-highlights-plot-release-highlights-1-4-0-py (look for the buttons at the bottom right hand menu ("lite" and "mybinder.org")

---

• I think this is the outcome of/motivation for the PR Daniel linked

[melissawm]

See also https://github.com/scipy/scipy/pull/20843

[lesteve]

Hi :wave:, not at the summit physically, but I am interested to help on this kind of topics!

For completeness: I did most of the work to get the scikit-learn gallery examples in JupyterLite, packaged OpenBLAS in Pyodide, and I am currently running the Scipy tests inside Pyodide in https://github.com/lesteve/scipy-tests-pyodide. The list of skipped/xfailed Scipy tests (with some short explanation) are tracked in https://github.com/lesteve/scipy-tests-pyodide/blob/main/conftest.py.

[thomasjpfan]

@lesteve From https://github.com/pyodide/pyodide/issues/3379#issue-1506105662, is the best way to debug RuntimeError: null function or function signature mismatch to use the Chromium? It looks like it's the best way to figure out which function has the mismatch.

[lesteve]

Yes, the best source I know is the Pyodide doc: https://pyodide.org/en/stable/development/debugging.html#linker-error-function-signature-mismatch and https://pyodide.org/en/stable/development/debugging.html#debugging-runtimeerror-function-signature-mismatch

If that happens in Scipy, generally you then need to go down the code generation in Scipy, the f2c hacks in Pyodide that do modifications before (on Fortran file) or after (on generated C file) f2c is run, etc ...

[betatim]

One thing that came up at the summit, and to which I'd also like to know the answer: is there a guide/example that shows how to solve the problem that the documentation on a dev website is ahead of the code packaged in the runnable examples (because pyodide doesn't contain the latest commit)?

[rgommers]

@betatim there's no answer as of today, but it's very actively being worked on (Cc @agriyakhetarpal and @hoodmane for visibility). The goal is to use nightly wasm wheels, the current blocker is that nightly wheels from https://anaconda.org/scientific-python-nightly-wheels/ aren't installable by Pyodide because the Anaconda index server isn't setting CORS headers. The resolution is either for Anaconda to fix that, or to run a proxy in front of that index server, or to move to a different hosting location.

Hopefully solvable in the coming weeks, with the guide on how to set up interactive docs ending up in a SPEC after that.