What’s new in 0.2.0 (Aug 13, 2024)

Setup by extension

Now you can add the myst_sphinx_gallery extension to the extensions list and specify the myst_sphinx_gallery_config variable in the conf.py file to configure the gallery.

conf.py

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

from pathlib import Path
from myst_sphinx_gallery import GalleryConfig

myst_sphinx_gallery_config = GalleryConfig(
    examples_dirs="../../examples",
    gallery_dirs="auto_examples",
    root_dir=Path(__file__).parent,
    notebook_thumbnail_strategy="code",
    thumbnail_strategy="last",
)

The parameters in the myst_sphinx_gallery_config variable will be used to configure the gallery. Available parameters can be found in the GalleryConfig class.

Tip

• The myst_sphinx_gallery_config variable can either be a instance of GalleryConfig class or a dictionary with the same keys as the GalleryConfig class.

• The GalleryConfig is recommended as it provides type hints, which can be helpful for IDEs and linters.

More details can be found in the Configuration for Generating Galleries section.

Enhancements for customizing

Thumbnail Configuration

Added a new class ThumbnailConfig to configure the thumbnail settings. The class supports custom thumbnail sizes, operations, operation arguments, quality, and more.

conf.py

from myst_sphinx_gallery import generate_gallery, GalleryConfig, ThumbnailConfig

generate_gallery(
    GalleryConfig(
        examples_dirs="../../examples3",
        gallery_dirs="auto_examples3",
        root_dir=Path(__file__).parent,
        thumbnail_config=ThumbnailConfig(
            ref_size=(320, 320),
            operation="pad",
            operation_kwargs={"color": "orange"},
        ),
        ..., # other configurations
    )
)

Customizing layout

In this release, we added the ability to customize the layout of the gallery using the Grid and GridItemCard classes.

Following code is an example of customizing the layout of the gallery:

conf.py

from myst_sphinx_gallery import generate_gallery, GalleryConfig, Grid, GridItemCard

generate_gallery(
    GalleryConfig(
        examples_dirs="../../examples3",
        gallery_dirs="auto_examples3",
        root_dir=Path(__file__).parent,
        grid=Grid(
            grid_args=(1, 2, 2, 2),
            margin=3,
            padding=2,
        ),
        grid_item_card=GridItemCard(columns=5, margin=3, padding=3),
        ..., # other configurations
    )
)

You can also using CSS to customize the layout of the gallery. More details can be found in the Customizing Style of Thumbnail and Card section.