sphinx-gallery for tutorials

[story645]

Hi,
Can't tell if this should be a feature request honestly, but wondering how you all would feel about using something like:

• https://sphinx-gallery.github.io/stable/index.html
• https://sphinx-nbexamples.readthedocs.io/en/latest/
  For your tutorials page so that you could have pictures to go along w/ the titles, maybe to make it easier to see what it's about?

[seanlaw]

Hi @story645! It's great to see you here.

I think it would be nice to turn each title into a card of some sort and along with an image. We recently switched over to using Myst and had considered laying things out as a grid of cards similar to Matplotlib (of course, that doesn't quite solve the "which image should go with which card" problem). We just haven't had any time to look at this but we welcome any help if you would like to contribute a PR! It would certainly make things look less bland

[story645]

Hi Sean!

Hmm...going by a convo w/ @agoose77 at Scipy, myst doesn't have a sphinx-gallery like thing (yet). :/
Wonder if it makes more sense to potentially build myst support into sphinx-gallery or if the plan is something standalone.

[seanlaw]

@story645 I did some digging and found this Myst-NB issue. Do you think that this is related?

going by a convo w/ @aagoose77 at Scipy

Did you mean to tag @agoose77 (single "a")?

[seanlaw]

I am way outside of my comfort zone on this (so I may be completely wrong here) but, based on this StackOverflow post, it may be possible to post-process an HTML but defining a Python function within conf.py. It is certainly less elegant to do it this way but, essentially:

1. Change contents of the tutorials.rst file so that it is formatted as a grid of cards with dummy/placeholder references to some yet-to-be-named image files that will be generated by Sphinx at build time
2. Add a new function to conf.py that will execute during the post-build process
3. Build everything as per usual
4. Execute (automatically) the new function in step 2 above to read through each built HTML file, grab the name of the desired .png image file, replace the dummy/placeholder in tutorials.html with the correct image name/location

I'm sure there are missing steps and I am completely wrong/trivializing things :)

[agoose77]

Thanks for tagging me everyone!

MyST-MD does not yet have a distributed extension for implementing a gallery of projects. Curvenote & 2i2c recently did some work with the Pythia community on something similar; https://github.com/projectpythia-mystmd/cookbook-gallery

We think that galleries-of-projects is a pattern that many people want to use, and should look to implementing something in this space. The way that we did this for Pythia is effectively generating the structured representation of a MyST grid at build-time, but a fuller implementation would actually add a new "widget" that our themes can upgrade with search boxes, filters, etc.