Example Gallery: Strategy and Reasoning

[michaelweinold]

Add a gallery like in e.g. pvlib. Potential packages: sphinx-gallery, nbsphinx, myst-nb.
See also this comparison.
Excellent example: ArviZ documentation example gallery

[michaelweinold]

sphinx-gallery/nbsphinx rely on each other to generate a gallery. However, they copy notebooks to an autogenerated directory that further complicates the build process and makes it nearly impossible to include images, etc.

Compary my issue here:

Embedding images in rst blocks currently broken, compare:

• Image in rst block not rendered correctly sphinx-gallery/sphinx-gallery#1063

We will not be using these packages.

[michaelweinold]

myst-nb package:

This package is by far the most powerful when rendering Jupyter Notebooks with embedded markdown. It is also part of the executablebooks project. As of now, it does not include a directive for generating a thumbnail gallery. However, multiple related issues are already open:

• Enable thumbnail galleries of notebooks executablebooks/MyST-NB#396
• [PROTO] Replace nbsphinx with myst_nb for example notebooks PlasmaPy/PlasmaPy#1474
• nbgallery thumbnails fill width with sphinx-gallery 0.11 spatialaudio/nbsphinx#655

We will wait until myst-nb supports a thumbnail gallery before adding it to the documentation.

[michaelweinold]

For now, the grid directive of the myst-parser is by far good enough for the example gallery.

This means that for now, the notebooks are not executed upon build and the gallery is not built automatically. However, it also means that building the gallery can be accomplished in myst-markdown alone. Also, no additional packages are required and the build does not become a complete mess.

[michaelweinold]

Tradeoffs:

package(s)	+	-	comment
sphinx-gallery	download example as ipynb can execute notebooks	example source must be .py no Markdown support	generates an autobuild folder
nbsphinx+sphinx-gallery	markdown support (.mystnb) can execute notebooks	no simple download option (possible through "prolog/epilog"
myst-nb	Markdown support	requires manual creation of gallery c̶a̶n̶n̶o̶t̶ e̶x̶e̶c̶u̶t̶e̶ n̶o̶t̶e̶b̶o̶o̶k̶s̶

[michaelweinold]

Decision

1. use myst-nb for now, with a manual grid of examples
2. wait until Enable thumbnail galleries of notebooks executablebooks/MyST-NB#396 has been implemented, then use this new functionality to auto-generate a gallery of examples
3. wait until Best way to download notebooks created from myst-notebook files? executablebooks/MyST-NB#148 is implemented, then use this new functionality to add a download button to the notebooks

[michaelweinold]

...the PyMC documentation has their examples in a separate repository: pymc-examples

• are they using myst-nb or Sphinx-Gallery?
• how are they integrating the examples into the main documentation

conf.py

"nb": ("https://www.pymc.io/projects/examples/en/latest/", None),

...currently, they are using their own script: pymc-examples/sphinxext/thumbnail_extractor.py

[michaelweinold]

• Enable thumbnail galleries of notebooks executablebooks/MyST-NB#396 (comment)

[michaelweinold]

https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

[cmutel]

@michaelweinold Could you add a brief note on the advantage of these MyST notebooks versus standard notebooks (sorry if this is obvious to you but it wasn't to me).

I also see an easy conversion to Jupyter Notebooks, but can we also convert the other way. We don't really want to rewrite working example notebooks unless absolutely necessary.

[michaelweinold]

@cmutel, the primary advantage is better diffing. While GitHub will likely release their current Jupyter Notebook Diff feature preview later this year, this would still leave local editors at a disadvantage. Working with .ipynb files can be a pain.

In the bigger picture, I doubt if we can transfer the present notebooks to either the JupterBook site or the JupyterLite hub site without 'renovating' them.

This issue here is helping me collect information on the two options we have to use Jupyter Notebooks with the Sphinx documentation.

[michaelweinold]

My discussion in the Executablebooks repo: sphinx-design multiple Grids with same Height

Potentially relevant:

https://sphinx-design.readthedocs.io/en/pydata-theme/css_classes.html#avatars
https://sphinx-design.readthedocs.io/en/pydata-theme/css_classes.html#sizing