Lazy loading of gallery thumbnails

[timhoffm]

Loading all tumbnails can take a significant amount of time/bandwidth (c.f. Matplotlib galleries).

It would be great if the loading could be deferred to the point when the user actually scrolls to the thumbnail.

Unfortunately, from a quick look this seems to not be easy. Lazy loading requires to change the <img> tag to either have an attribute loading='lazy' or use data-src instead of src(https://www.sitepoint.com/five-techniques-lazy-load-images-website-performance/) The thumbnail is generated via a .. figure:: directive (see THUMBNAIL_TEMPLATE), which does not expose any of those.

Ideas are welcome how this could be solved.

[larsoner]

In lieu of modifying docutils to add this sort of support, which they might not even go for, we could consider adding our own .. lazyfigure:: directive that subclasses the standard figure one but overrides the HTML formatting to add this extra loading='lazy' (or JS with data-src or whatever).

Maybe even easier would be to add a JS library that modifies the HTML at load time to have this loading=lazy attribute, but I'm not sure if that would even work (the browser might already be trying to load the images by the time the element is updated).

[timhoffm]

I've posted a feature request to docutils. https://sourceforge.net/p/docutils/feature-requests/78/

Let's see how that goes.

[tacaswell]

It seems the upstream feature request was implemented!

Implemented in Docutils 0.18. Thanks again for the suggestion.

[lucyleeow]

Great. Should this be closed now then?

[timhoffm]

My original idea was that this setting was applied to the gallery thumbnails only.

This would require an image option

.. image::
   :loading: lazy

AFAICS, docutils has not implemented that. docutils 0.18 only added a global config parameter https://docutils.sourceforge.io/docs/user/config.html#image-loading but not a per-image setting.

Does this handle this issue?

I think that depends. The core issue here is that we want incremental loading of gallery images. Is it ok to tell users to globally switch to lazy loading for all content? If yes, then we can close. If no, we'd need to go back to docutils and request the per-image option, and when that's done add a sphinx-gallery option to set that option for all thumbnails.

[tacaswell]

I would be happy with a global flag on the mpl docs. I found this issue after clicking the "simulate on slow 3G" button in the browser dev tools for the mpl docs and I think that all of our images should be lazy (better to show a page without images than nothing for like 2.5 minutes).

[timhoffm]

I'm fine with the global solution for matplotlib (which motivated the PR). The disadvantage from sphinx-gallery's perspective is that every library has to activate tat setting themselves (and know about it). sphinx-gallery cannot pre-configure that global flag, which results in a less good default configuration. Maybe you still want to add a section about it in https://sphinx-gallery.github.io/stable/configuration.html even if it's not strictly a sphinx-gallery configuration.