myst-sphinx-gallery

Introduction

MyST Sphinx Gallery is a Sphinx extension that allows you to build galleries from jupyter notebooks (.ipynb), markdown (.md) or reStructuredText (.rst) files.

This extension is functionally similar to the Sphinx-Gallery extension, but aim to provide a simple and efficient way to create galleries written in a variety of file formats.

Highlight Features

• Easy to use - It provides a set of directives to generate galleries, as simple as adding toctree.
• Flexible - You can easily generate a gallery of examples from your Jupyter Notebooks, Markdown, or reStructuredText files. It works with MyST Ecosystem, including MyST-parser and MyST-NB, to render markdown or jupyter notebooks in Sphinx documentation.
• Fast and robust - It utilizes existing images to generate gallery thumbnails, eliminating code execution delays and potential accidental errors when building gallery.
• Customizable - You can customize the gallery, such as thumbnail selection, and style of the gallery.

Documentation

The detailed documentation is available at: https://myst-sphinx-gallery.readthedocs.io/en/latest/

Quick Start

[!NOTE] The quick start guide here is a brief introduction to the MyST Sphinx Gallery extension. More detailed Quick Start guide is available at: Quick Start.

Installation

MyST Sphinx Gallery is a Python package, and requires Python >= 3.8. You can install the latest release using pip from the PyPI:

pip install myst_sphinx_gallery

or using conda / mamba from the conda-forge channel:

conda install -c conda-forge myst-sphinx-gallery

mamba install -c conda-forge myst-sphinx-gallery

Configuring the extension

Enable the extension

After installation, you can enable the extension in Sphinx conf.py file:

  extensions = [
      ...,  # other extensions
      "myst_sphinx_gallery",
  ]

[!IMPORTANT] MyST Sphinx Gallery only helps you to generate the gallery. You need to enable the MyST parsers to render the markdown or jupyter notebook files by yourself.

For instance, to enable the MyST-NB, you can add the following code to the conf.py file:

extensions = [
   ...,
   "myst_nb",
]

source_suffix = {
   ".rst": "restructuredtext",
   ".md": "myst-nb",
   ".myst": "myst-nb",
}

For more information, please refer to the documentation of MyST and MyST-NB.

Configuring the variables

MyST Sphinx Gallery has two main configuration variables that can be set in your conf.py file.

• myst_sphinx_gallery_config : global configuration for all examples using gallery directives or used to generate galleries.
• myst_sphinx_gallery_files_config : configuration for individual files to override the global configuration for those files.

[!TIP] Those two variables are optional and can be omitted if you don't need to customize the behavior of MyST-Sphinx-Gallery.

More details about the configuration variables can be found in the Configuration Variables section.

Generating gallery

There are two ways to generate galleries in MyST Sphinx Gallery:

1. Using directives: MyST Sphinx Gallery provides three directives for generating galleries: base-gallery, gallery, and ref-gallery. You can directly use these directives to generate galleries in reStructuredText (.rst), Markdown (.md), and Jupyter Notebook (.ipynb) files.
2. Configuring in conf.py: You can also generate gallery by specifying the examples and gallery directories in your conf.py file. This method is keeping in line with Sphinx Gallery extension.

[!NOTE] Using directives is highly recommended for generating galleries as it provides more options and flexibility. For instance, you can add tooltip to example cards, call different directives multi-times in a single file to generate a complex gallery. This cannot be done using the configuration method.

You can refer to the Generating Galleries Methods section for more details.

Select the thumbnail for an example file

• one image - If there only one image in an example file, no additional configuration is needed, and that image will be used as the gallery thumbnail.
• multiple images - If there are multiple figures in an example file, you can specify the strategy to determine which thumbnail will be used for the gallery. The following strategies are supported:
  1. alt - If the alt attribute of an image/figure is set to gallery_thumbnail, that image/figure will be used as the gallery thumbnail for this file.
  2. first/last - If there are multiple images that can be used as the gallery thumbnail, the first/last image will be selected. You can specify the strategy by setting the thumbnail_strategy in the configuration file. The default value is first.
  3. code/markdown - For Jupyter notebook files, both markdown and code cells can contain images. You can specify the strategy by setting the notebook_thumbnail_strategy in the configuration file. The default value is code.
• no image - If no image/figure is found, the default thumbnail will be used.

More details can be found in the Thumbnail Strategies.

Customizing style of thumbnail and card

You can customize the layout and thumbnail behaviors for the gallery using the MyST Sphinx Gallery extension. For more details, please refer to the section Customizing Style of Thumbnail and Card .