MyST-NB

MyST-NB copied to clipboard

Describe the problem/need and solution

Context I'm working on a pull request to consider switching from nbsphinx to MyST-NB. Our documentation currently has thumbnail galleries that were created using the nbgallery directive from nbsphinx. The instructions in the MyST-NB documentation currently state that the notebooks should be included in a Sphinx :toctree: directive, which puts them in a table of contents format without thumbnail images.

Problem / Idea I would like to use MyST-NB and be able to generate thumbnail galleries of example notebooks.

Solution

Ideally, I would like to be able to use a directive similar to nbgallery from nbsphinx when using MyST-NB. One possibility would be to make it so that this directive would be able to be used when MyST-NB is enabled as a Sphinx extension.

Another possibility would be to add an example in the documentation of how to use another Sphinx extension to create a thumbnail gallery while using MyST-NB for processing notebooks.

Benefit

The ability to generate a thumbnail gallery would remove a blocker that could prevent projects from switching to MyST-NB from nbsphinx or sphinx-gallery.

Guide for implementation

This comment describes a hack to generate a thumbnail gallery via nbsphinx while still using MyST-NB for tasks besides the thumbnail gallery.

My current understanding is that the code used to generate a thumbnail gallery has generally been bundled to the code used for processing notebooks. Ideally these would be decoupled from each other, which would make it easier to switch between sphinx-gallery, nbsphinx, and MyST-NB.

Along these lines, I'm also wondering if it would be possible to import only the nbgallery directive from nbsphinx to avoid needing to duplicate code.

Thank you!

Tasks and updates

No response

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

Heya, just to quickly note, I am certainly interested in something like this 👍 I feel, perhaps even more generally than sphinx-gallery or nbgallery, you could have an extension that simply generates a thumbnail gallery from any list of documents, a little similar to how ablog works (which is already integrated with myst-parser / myst-nb):

See e.g.:

• https://ablog.readthedocs.io/en/latest/manual/markdown/
• https://ablog.readthedocs.io/en/latest/manual/post-excerpts-and-images/#images
• https://executablebooks.org/en/latest/updates.html

Just to say that I support that, it would be a great feature!

This would be quite useful for pymc as well: docs.pymc.io

@twiecki, it seems that PyMC Examples already has a neat script set up to generate a gallery of notebooks:

pymc-examples/sphinxext/thumbnail_extractor.py

Could this be adapted for use with MyST-NB? Would be happy to contribute to the PR once you have a first draft.

We would be happy to see this feature in MyST-NB, since sphinx-gallery relies on nbsphinx to generate a gallery.

@michaelweinold That is using NBs directly it seems. I'm sure it could be adapted but I won't be able to help in that effort but would cheer on any such effort :).