GeezerVison

Super cool to see this!

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 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

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¹. 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? ²), 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. :)

Thanks for the time you are investing in the ecosystem, @agriyakhetarpal!

I haven't had a chance to look at the PR, but just wanted to drop a link to the SPEC Purpose & Process document, which is important background reading for all SPEC authors.

Thank you, @stefanv ! I can confirm that I've read through it – I did so before I opened the PR. 😃

I was also wanting to open a post on the Discourse forum as per https://scientific-python.org/specs/purpose-and-process/#new-spec-proposals, but it turned out that I don't have permissions to do so. Who may I contact to receive them?

This is me: https://discuss.scientific-python.org/u/agriyakhetarpal/

Alternatively, if you or someone else could post it on my behalf, that would also be fine with me. :)

I was also wanting to open a post on the Discourse forum as per https://scientific-python.org/specs/purpose-and-process/#new-spec-proposals, but it turned out that I don't have permissions to do so. Who may I contact to receive them?

As long as you are logged in, you should be able to post there:

Can you take another look, and let me know?

Thanks! Don't mind me: I was looking at https://discuss.scientific-python.org/c/specs/6, which is restricted, but https://discuss.scientific-python.org/c/specs/ideas/9 is open for me. On it!

As a project maintainer I enjoy SPECs or guides that directly show me what I need to do to implement them. Not sure how typical I am but I find often that I read a SPEC or a guide once I am already convinced that something is a good idea and the open question is: how much work is this going to be and how easy is it to maintain? To answer this I look at examples like the jupyter lite one, but then also "real world" examples like "can I work out how much stuff Numpy had to do to get this?". This is why I'd vote for putting such information early.

Maybe I should have added it in my first comment: I helped build and run mybinder.org for a few years, so I am biased about it :D - things like thebe were made with interactive docs in mind. But after thinking about all this, I think the SPEC is already quite long and useful(!) so maybe it is smarter to not make it longer. Instead there could be a new SPEC about things like thebe and binder, if there is enough demand.

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.

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 think @betatim is right. High-level picture and happy-path-first matter. Too much "messy aspect" stuff first is almost never the right thing to do, it will be confusing to the reader new to the topic - try to defer as much as possible to later in the document, to an appendix, or to an external link.

@agriyakhetarpal As an FYI, here are some brief Binder resources:

• https://jupyter.org/binder
• https://blog.jupyter.org/mybinder-org-serves-two-million-launches-7543ae498a2a
• https://doi.org/10.25080/Majora-4af1f417-011