This is an inventory assuming #17477 goes in & a later upgrade to sphinx 0.7.1

Minor note, even the one that requires ArtistAnimation will have a thumbnail with that PR ("precomputed list of images"):

https://37252-1385122-gh.circle-artifacts.com/0/doc/build/html/gallery/index.html#animation

So it's not dependent upon Sphinx-gallery 0.7.1, just the animation of the thumbnail EDIT: and embedding of the animation will be. Unless you're referring to a different example...

Generally 👍, e.g. the embedding examples could show a screenshot.

Even though it's called "Gallery" in the section title, I consider them more broadly as "Examples" (as is the top-level menu navigation item pointing to the gallery).

With that interpretation, not every element in the gallery must have an image. Some times there is just no visualization and the default placeholder is fine, e.g. for https://matplotlib.org/devdocs/gallery/misc/font_indexing.html#sphx-glr-gallery-misc-font-indexing-py

I think the ones that don't have pictures should maybe be moved to a different part of the docs - either integrated into a tutorial or maybe a section of the gallery that's explicit about it not being visual.

I think the placeholder ends up creating confusion (is this example broken?).

I consider the thumbnail as a nice but optional illustrative add-on, but not as the essence of the example.

(I would even be +0.5 on renaming "gallery" to "examples", the latter being more self-explanatory.)

not as the essence of the example

I think it's the key part of the example, especially because visualization nomenclature isn't remotely consistent so often the thumbnail is what folks are working off of to figure out if this example will do the thing they want. I also think one of things Matplotlib most has as an advantage is it's a visualization library so can have visual examples that show what effect code is supposed to have. One of the very frustrating parts of a lot of the examples is they get so boiled down in boilerplate that it can sometimes be hard to figure out which line of code is responsible for the important bit & the thumbnail helps signpost that.

So the gallery is renamed examples and has been for years (to the chagrin of some users), but that's almost a pedantic distinction given that there are like 627 examples of which maybe 30 are missing thumbnails. Except for widgets, there's no consistency in what's missing a thumbnail which is what makes the missing thumbnails look like an error. I have 0 issues with examples that don't provide a thumbnail if the examples can be reorganized such that it's clear that the choice was intentional.

This can be as simple as adding an explicit "code examples" section to the gallery or alternatively what about a "this is code" thumbnail - little picture of code, something similar that makes it clear it wasn't a sphinx autogen fail?

Hello @story645, I am Kritika Gupta final year B.Tech ECE student. I am interested to apply for GSOD. Want to start by contributing for this issue.
Please let me know how to get started?

Things that can be done for this issue:

• take screenshots for the embedded guis - I'm now kind of wondering if this can't be automated with something like selenium or preferably just system tools
• Run the other examples and see if they generate a useful image/something that can at least be screenshotted - if they generate an image, investigate why that's not being used as the thumbnail
• Propose a thumbnail image for our code examples - this must be licensed such that we can use it & preferably would be an image generated specifically for this use case so that there are no licensing issues.

The instructions for adding the images are listed above & the images should be as small as possible. For now add a folder to examples for thumbnails but expect it to be moved.

Hey @kritika12298 ! I'm also looking into the same issue. However, I am just starting with it. Do you have an understanding of how the docs are generated? I couldn't find any clues except this file which seems to generate them. I may be completely wrong, though. I would really appreciate your help. Thank you :)

the docs are built same as the code & you're going to need the most current source code so please follow the instructions at https://matplotlib.org/devdocs/devel/index.html

@story645

What about a "this is code" thumbnail [...] that makes it clear it wasn't a sphinx autogen fail?

I did not check, but I assume our doc build would fail if the example did not run properly. (And disregarding that, it would be better if failing examples got a special thumbnail directly by sphinx gallery, e.g. a warning sign).

Overall, I'm not fundamentally opposed to a special non-plot thumbnail, I just don't think it's necessary.

I did not check, but I assume our doc build would fail if the example did not run properly.

For example, the annotations tutorial has a bunch of images embedded in it and any one of those could be the thumbnail. That it isn't is either misconfigured sphinx or an intentional choice - a specific thumbnail would help flag which.

• take screenshots for the embedded guis ...
• Run the other examples ...

The easiest solution I can see is that you run the code on your own machine, make a static image of it, and make some new StaticScraper class as a custom sphinx-gallery scraper for it. You could also go much more complex and build a scraper that would use selenium or something else to actually screenshot a GUI for example. For sphinx-gallery you just need to write to the correct image paths and return RST to embed. It probably wouldn't need to be more than 20 lines of new code plus a sphinx_gallery_conf modification.

I did not check, but I assume our doc build would fail if the example did not run properly. (And disregarding that, it would be better if failing examples got a special thumbnail directly by sphinx gallery, e.g. a warning sign).

See the sphinx-gallery docs and example in practice. You can mark examples as expected to fail. In theory we could figure out how to make this more configurable -- for example right now I don't think you can change which thumbnail is used in these cases. If you wanted a custom one, we could add that -- or if you wanted a BROKEN overlay put on top of any scraped image (if there was one) you could do that, or you could combine the custom-BROKEN + overlay idea, etc. These are not too difficult under the hood in Sphinx-gallery, just haven't hit a use case for them yet...

... actually it looks like the static-image case can already by fairly easily taken care of with # sphinx_gallery_thumbnail_path = _static/whatever.png. This can also solve your annotation example (linked to the wrong one above I think) -- it doesn't have a thumbnail currently because no images are scraped by Sphinx-gallery (the code just embeds images from other examples). So a one-line # sphinx_gallery_thumbnail_tpath would take care of this similarly.

Thank you @larsoner

(linked to the wrong one above I think)

Yes, 🤦 thanks for the right one

You could also go much more complex and build a scraper that would use selenium or something else to actually screenshot a GUI for example. For sphinx-gallery you just need to write to the correct image paths and return RST to embed

Thanks for this tip! I think long term this is the more robust solution as it would account for updates in the GUI package.

I think long term this is the more robust solution as it would account for updates in the GUI package.

Agreed it's better in principle but in practice it will require potentially much more difficult dependencies and code maintenance. I would not go this route personally just to make a small percentage of examples have a screenshot, but I am not a mpl dev so I leave it up to the folks here to decide...

actually it looks like the static-image case can already by fairly easily taken care of with # sphinx_gallery_thumbnail_path = _static/whatever.png

Just looking into this, the problem with # sphinx_gallery_thumbnail_path is that it needs to be outside of the docstring, which makes it complicated for examples like annotation.py which is all docstring. Adding a code block under the docstring will work but will result in an empty code block at the end of the example.

is this issue still open???

yes! @ianhi might be working on something for the widgets, and it may be better to tackle the sphinx gallery bug first.

A maybe overengineered solution to the widgets is discussed #19222 which proposes using https://github.com/ianhi/mpl-playback which provides a sphinx-gallery scraper that should be robust to style changes.

I think long term this is the more robust solution as it would account for updates in the GUI package.

How about using https://pillow.readthedocs.io/en/latest/reference/ImageGrab.html to grab the screenshot of the gui window? Making a custom sphinx gallery scraper is pretty easy it turns out! Here's the mpl-playback one: https://github.com/ianhi/mpl-playback/blob/409e6fc68cdec4b59ce56231cbbd4d117647d3f4/mpl_playback/scraper.py#L66

So my proposal for the GUI images:

1. Create a file that lists the example name and the bbox to screenshot
2. Write a custom scraper that checks if the current example is in that file
   a. If yes: using pillow screengrab
   b.If no: just pass all args through to the default sphinx-gallery scraper

Hi @larsoner , I want to add a thumbnail to this https://matplotlib.org/devdocs/gallery/index.html#embedding-matplotlib-in-graphical-user-interfaces example. Could you please suggest a step by step procedure ? I see there are lots of suggestions here.

... actually it looks like the static-image case can already by fairly easily taken care of with # sphinx_gallery_thumbnail_path = _static/whatever.png

For the above to work, what file do I need to add this line # sphinx_gallery_thumbnail_path = _static/whatever.png ?

Should I take the pics for the thumbnail from the example itself ?

Personally now that I know about https://github.com/ixjlyons/qtgallery I would try that first and see if it gets you what you want without any extra # sphinx_galllery... comments or manual screenshots.

For the above to work, what file do I need to add this line

Can you see if the docs make this clear? If not we should fix them

https://sphinx-gallery.github.io/stable/configuration.html#providing-an-image-for-the-thumbnail-image

Should I take the pics for the thumbnail from the example itself ?

I would but that's a matplotlib content question more than a SG one so I'll defer to the mpl folks for that

Thanks for the reply @larsoner . But I'm little confused here. Do I need to set up a https://matplotlib.org/devdocs/devel/development_setup.html matplotlib development environment first and then install qtgallery ?
Or the qtgallery is a standalone one ? First I have to install by pip install sphinx-gallery this and then the instruction given in the qtgallery ?

I would but that's a matplotlib content question more than a SG one so I'll defer to the mpl folks for that

I agree that if possible, the thumbnail should come from the example.

@ggold7046 matplotlib is still the development environment 'cause you'd be sorting out how to get qtgallery enabled with matplotlib.

@ggold7046 matplotlib is still the development environment 'cause you'd be sorting out how to get qtgallery enabled with matplotlib.

So, is there any easy issue that I can try ?

Hi @ggold7046 - I believe the first suggestion is to add qtgallery as a scraper to the matplotlib gallery (here are the instructions: https://github.com/ixjlyons/qtgallery#configuration)

This should be added in https://github.com/matplotlib/matplotlib/blob/main/doc/conf.py, and you can either build the docs locally to test that it worked or, if that's too cumbersome, you can submit a draft PR to the Matplotlib repo and wait for CI to run and display a preview of the built documentation.

I have to say I am not sure that will be enough to solve your problem, so it may be that you need a few iterations of tries to get that working :) Please feel free to reach out if you have other questions!

Do I need to add those three dots in conf.py or is it just for continuation of other codes ?

Those are just for continuation

I'd slow down here - we already have a way to display animations in the gallery, so I'm not clear why we would use a different scraper just to get the thumbnail.

I'm not clear why we would use a different scraper just to get the thumbnail.

My suggestion was to use qtgallery to capture plots of matplotlib embedded in Qt windows to help with the "Toolkits" section at the top rather than animations

I think that works for a few of the examples if they were rewritten? But https://matplotlib.org/devdocs/gallery/user_interfaces/index.html uses a bunch of other backends. It seems to me that if we want this to look nicer, screenshots is a reasonable, if laborious and fragile, way to go? #17479 (comment)

Personally, I'd just remove the README.txt and replace with an index.rst with a manual table of contents for the few galleries that are all broken.

Also @ianhi 's mpl-playback is a more backend neutral version, so @ggold7046 if you're going to invest your time in this it may otherwise be more worthwhile to invest it there #23441 (comment)