A new perspective on providing example galleries

[kolibril13]

My idea in short:

A Jupyter cell magic, that takes the code of a cell and the corresponding example output image. The cell magic then generates a html website, where one can see a gallery of all examples. When one clicks on an image on the website, the code pops up. I've already written a prototype, here is a screen recording where you can see this idea in action:

https://user-images.githubusercontent.com/44469195/146995849-7a0edab8-281b-4cf4-95ba-9afb8e79ebde.mov

This can be extremely useful for all libraries that produce image cell output. With this cell magic, one can always keep code and output image close together and has a nice overview without the need to open the Jupyter notebooks. Projects where this might be useful, can be e.g. scikit-image, matplotlib, scipy, napari, or manim.

And now the cool thing: This gallery can then simply be uploaded as a static website, e.g. at Github pages. As I am quite active in the manim project, I've already built a gallery: https://kolibril13.github.io/mobject-gallery/

And even cooler: This gallery can also be used as a VS Code extension, you just click on one image, and the code snippet gets directly pasted to your VS Code jupyter-notebook, this VS Code extension also already exists for Manim, you can find an impression in this tweet: https://twitter.com/FlyingFramesIO/status/1469732058532618249

What happens under the hood: The jupyter cell magic capture_png, that I developed together with @krassowski_m saves the output image in a separate folder. Furthermore, a json file is generated, that has the image path as a key, and the python code block as a value. To the front end: There is a html page which is the canvas. A JavaScript file checks for the json file and when it finds content in it, it reads the image path and the corresponding code-string. Lastly, there is some css involved to display the gallery correctly. This was build as a prototype, therefore the code still looks like a mess, but it everything works as expected.

Pinging @jni and @tupui, as it was pleasant to be reviewed by you in my recent pull requests where I made some small contributions to the example galleries, you might be interested in this idea.

I think this has big potential: not only can package developers use this feature to create cheat sheet like overview galleries of their libraries, but also python users can use this feature to build their own personal snippet gallery. I know that there are already popular snippet tools, but I think this tool is special: Normally, snippets work in a way that text is mapped to text. But here, we have text, that is mapped to images, and from my experience, the human association works better for images than for text files. Looking forward to your replies!
I've published the draft gallery from the screen recording here: https://kolibril13.github.io/okapi/

This issue was first posted at https://github.com/scikit-image/scikit-image/issues/6135 and @tupui suggested having the exchange in this repo, that's why I moved the issue.

[12rambau]

What you did is super cool ! I think I'll use it for some of my personal projects.

On the other hand I fail to see where we could use it in this sphinx theme as we are not providing support for how galleries are made in the libs documentations. I see it more like a Sphinx extention than directly a part of this repository.

Can someone elaborate on what could be the future of this in the pydata-sphinx-theme framework ?

[12rambau]

If someone which to explain why this should be implemented directly in pydata-sphinx-theme instead of as a sphinx extention please reopen the issue.

As of now, it seems it won't be done directly here as mentioned in my previous comment.