SPEC 14: Interactive Documentation by agriyakhetarpal · Pull Request #388 · scientific-python/specs (original) (raw)

Thanks for the nice initial feedback, @betatim!

One feedback on the organisation: I started reading the SPEC and only after covering a lot of "stuff" did we get to a section that explains to the reader how to do this for their project. Can we somehow change the order? I think most readers will be looking for information on "is this interesting/cool to do?" (we can answer this with screenshots and linking them to existing examples) and then if they want to do this the next question is "How do i do this for my project?". I think only after that will people worry about things related to CI, etc

Yes, this is something we've considered, and it raises the question of the audience/readers for these SPECs. I might be wrong here: while these have been meant for maintainers and developers of core projects who would like to know the messy aspects upfront before deploying anything, I've seen recent shifts in the marketing of these SPECs as they are also being written for projects outside of the core ecosystem, where the assumption that their package is already in Pyodide/emscripten-forge (like it is for most core projects) may not hold and they have to go through these steps anyway.

I agree with your comment, though. I think an "Overview" section with a few live examples sounds best here (and we can move the NumPy example screenshots within that section). It should also be possible to include a notebook from the scikit-learn documentation within the page in an iframe if that helps :)

Or put differently: I think we should try and make it as easy as possible to get people started (and then hooked on :D) having interactive docs. Even at the cost of then, once they are hooked, "disappointing" them with "well, actually, it isn't all as easy as we made it look at the start". What do you think?

💯!

Completely different topic: how popular is mybinder.org for interactive docs that don't work in jupyterlite? I think for most use-cases it isn't needed, but maybe someone who is a bit more plugged in to this has an idea. We still use it for scikit-learn, but even I mostly use the jupyterlite badge these days

I've never actually used Binder either 😄 However, I imagine that server-side computation for interactive documentation, as opposed to its client-side counterpart, also has a fair bit of users 1. Besides direct usage, Sphinx-Gallery offers the Binder badge in the sidebar that you've mentioned of course, and there are a few projects that that were built with similar goals in mind: https://github.com/executablebooks/sphinx-thebe and https://github.com/jupyter-book/thebe (the latter also has a thebe-lite package that can work with Pyodide, but I haven't used it). So while I don't have a clear answer to this as I've never run any metrics to find out (and I don't think Plausible Analytics tracks the /lite/lab/ pages for the JupyterLite case, does it? 2), I think we should refrain from mentioning anything more about it besides the one sentence we have added in the "Runtime considerations" section, and our stance is going to be limited to Sphinx (see also: scientific-python/summit-2025#25 (comment)). We could also consider renaming the SPEC to "WebAssembly-powered Interactive Documentation" if that serves the topic better, but I can guess that the consensus would be that no one would like hosting a server for this and utiling WebAssembly for this would be the norm in the coming time as tooling matures. :)

Maybe someone from the mybinder.org or the https://2i2c.org/ teams could help get us some analytics here :D ↩
Note to self: check this and see if we can include this functionality in JupyterLite itself, also xref: https://github.com/jupyterlite/jupyterlite/issues/1637 ↩