Repository navigation
Add gifs of usage to widget examples #19222
Description
Problem
It can be hard to discern what a widget example does as for many of them there are no images that show up in the docs. For example the Lasso Selector Demo has no image and the Lasso Demo only has a static image.
Suggested Improvement
Manually generate GIFS of the usage and embed them onto the example pages. For example here is a GIF of me using the LassoSelector demo:
I'm not sure if sphinx-gallery supports this though? maybe embeding and html <img> tag into the comment at the top would work?
Also instead of .gifs I it would be better to keep files small by using .apng and running them https://tinypng.com/
Reacted by hannah and Rishabh Varshney
Activity
story645 commentedon Jan 3, 2021
Agree, and also #17479 has a discussion on the viability of doing something automated.
timhoffm commentedon Jan 4, 2021
The animation is a useful addition to make the widget examples more easy to understand.
This is not particular difficult but somewhat tedious because AFAICS it will need some manual steps and explicit configuration.
Automated creation:
While it may be possible to automatically generate a sceenshot from the user interface (as suggested in #17479), this animation here requires user interaction, which is more complicated. I assume it's not worth the effort to script user interaction for the examples.
Manually generate GIFS
I'm happy to see it if somebody takes the responsibility.
What would have to be done:
.. image::directive.The whole process (in particular also the tooling used in 1.) should be described in the documentation guide so that we and others are able to reproduce it if necessary.
Remark: It may be reasonable to get in touch with sphinx-gallery if the want to integrate something like a "standalone image", that combines 2. and 3. into a single command. I imagine that this could be useful for other cases that don't generate a in image (not necessarily animated) in the example code.
QuLogic commentedon Jan 5, 2021
We do have a way of mocking events to widgets, so it might be possible to write some automated way to generate these. It would still require some work somewhere though to implement it all.
timhoffm commentedon Jan 5, 2021
The downside is that you don't get the cursor. IMHO seeing the cursor movement significantly helps in understanding what's going on.
ianhi commentedon Jan 10, 2021
I agree that seeing the cursor is crucial for understanding, however manually recording the GIFs is also sad times because it would need to be redone anytime the styling changes. I think we can get the best of both worlds by doing:
This also carries the extra advantage of not increasing the repo size as the only thing that is persistent is a text file of the mouseevents.
timhoffm commentedon Jan 11, 2021
Um, this is doable but sounds like a medium size effort. I'm somewhat reluctant taking this on in core Matplotlib. 1-3 could be developed as a 3rd party package.
jklymak commentedon Jan 11, 2021
Agreed - this is a lot of machinery for something the user could just try themselves from the example.
The low-tech way of doing this is to do them by hand, and then putting a comment in the widget code noting that they should be modified if there are major changes. That is pretty low maintenance and it is not like widgets are changing very often.
ianhi commentedon Jan 11, 2021
I think it makes sense as a third party package. I would use this, and I think animatplotlib would also find it useful. To that end I couldn't get it out of my head so I did some maybe terrible things using
execand made this https://github.com/ianhi/mpl-playbackWhich I used to generate this gif:
ianhi commentedon Jan 11, 2021
But I hear the arguments about not adding extra machinery. If matplotlib ends up going the route of manually recording gifs I won't be made sad :)
story645 commentedon Jan 11, 2021
Is there also the option of making it a 3rd party package that is then a dependency in the doc builds?
QuLogic commentedon Jan 11, 2021
This is essentially what I would do, with some small tweaks. Sphinx-gallery has a custom scraper API, so I would use that instead to create and inject the resulting GIF.
ianhi commentedon Jan 12, 2021
Thanks for the pointer @QuLogic, that does seem to be the correct approach. I don't think I handled the thumbnail stuff correctly yet, but here is a working gallery with GIFs:
https://mpl-playback.readthedocs.io/en/latest/gallery/index.html
edit: almost working it turns out. On readthedocs only the thumbnail renders, not inside the example. Which is different than locally 🤔(edit2: now it all works 🎉)github-actions commentedon Sep 25, 2023
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!