WASM-based interactive docs and docs restructuring

[Haleshot]

What would you like?

An interactive documentation (playground) embedded directly within the docs site using WebAssembly (WASM). This will allow users to modify plot configurations or parameters via inline blocks and see the outputs of graphs render live in the browser.

This issue follows up on a brief email exchange with the @Psy-Fer and I. It is meant to be a tentative proposal with the intention of having others weigh in with their thoughts on possible approach/es (especially those who have designed interactive documentation from the ground up).

Use case

Currently, mapping color configurations, builders, and API references requires significant vertical scrolling (since all are stated on one doc page). A general cleanup and reorganization of the layout is needed to make the plot types and API references easier to navigate.
Also, adding interactivity directly to the plotting pages lets users test configurations and experiment with code samples right on the page. Rather than reading static documentation, developers can tweak builders or switch options inline to see the immediate effect on the output.

Any prior art?

• The HoloViz Panel plot viewer template shows a clean way to track configuration widgets right next to a visual canvas component to avoid a scrolling maze.
• The sphinx-marimo WASM examples and the MyST AnyWidget Directive post demonstrate execution models where documents run reactive code directly over WASM without server-side backends.
• The recent marimo-anywhere blog post.

[Psy-Fer]

This will take a bit of doing to get wasm working, though kuva has been designed with this in mind from the start. It's just easier said than done 😆

Using the docs as a testing ground for each plot will also be... The testing ground 😅 so that will work well.

I'll get to this soonish

James

[Psy-Fer]

First step to this was doing a re-organisation of the docs, and I did some research for WASM preparation. So this is now all lined up for a future release. Doc changes will land in next release, but those are mostly re-organisations and css updates.

So in a future sprint, I will solve any blockers getting to WASM. Then a sprint after that, i'll implement it. Then after that, i'll build an interactive plot builder around it, and host it in the docs, so users can build plots interactively, then it will give them the code to generate those plots.

To this end, I added an --emit-code arg to the CLI that will give the user the library code to remake the same CLI plot, but with the library. This was me doing an early prototype for that interactive plot building feature.

Anyway, wanted to drop a bit of progress and how things are coming along.

Cheers,
James

[Haleshot]

Happy to help as needed whenever :)
Thanks for posting the update!!

PS: Also I hope this doesn't come across as promotional: given that the work being done in this thread is related to documentation work, you should definitely check out the Write-the-docs australia CFP and consider submitting a talk based on your experience during this whole migration process