myst_sphinx_gallery.config#

Configuration classes for the gallery.

Classes

`FilesConfig`(named_config, ...)	Set different thumbnail configuration for different files.
`GalleryConfig`(examples_dirs, gallery_dirs, ...)	Configurations to generate the gallery from examples.
`GalleryThumbnailConfig`(thumbnail_strategy, ...)	Configurations to generate the gallery from examples.
`ThumbnailConfig`(ref_size, int] =, operation, ...)	Configuration to setup the `Thumbnail` class.

class myst_sphinx_gallery.config.FilesConfig(named_config: dict[str, ~myst_sphinx_gallery.config.GalleryThumbnailConfig] = <factory>, files_config: dict[str, list[str]] = <factory>)[source]#

Set different thumbnail configuration for different files.

named_config: dict[str, GalleryThumbnailConfig]#

A dictionary giving the names for different configurations.

The key and value of the dictionary are the names and configurations of the thumbnail configurations, respectively: {name_of_config: GalleryThumbnailConfig()}

files_config: dict[str, list[str]]#

The configurations for different files.

Note

The key of the dictionary is a name string of the configurations in named_config, and the value is a list of paths to the files: {name_of_config: [path_to_file1, path_to_file2, …]}
The paths are relative to the conf.py file.

to_dict() → dict[source]#: Convert the configuration to a dictionary.

get(file_path: str) → GalleryThumbnailConfig[source]#: Get the configuration for a file path.

class myst_sphinx_gallery.config.ThumbnailConfig(ref_size: tuple[int, int] = (320, 224), operation: ~typing.Literal['thumbnail', 'contain', 'cover', 'fit', 'pad'] = 'pad', operation_kwargs: dict[str, int] = <factory>, max_animation_frames: int = 100, quality_static: int = 80, quality_animated: int = 50, save_kwargs: dict[str, int] = <factory>)[source]#

Configuration to setup the Thumbnail class.

This class is used to specify the parameters to create a thumbnail from an image.

ref_size: tuple[int, int] = (320, 224)#: the reference size of the thumbnail image for output.

operation: Literal['thumbnail', 'contain', 'cover', 'fit', 'pad'] = 'pad'#

The operation to perform on the image.

See the Pillow documentation for more information: https://pillow.readthedocs.io/en/stable/handbook/tutorial.html#relative-resizing

operation_kwargs: dict[str, int]#: The parameters passed to the operation function.

max_animation_frames: int = 100#: The maximum number of frames to extract from an animated image. If the image has more frames, will sample the frames uniformly.

Tip

If you want to make the thumbnail of animated images to be static images, you can set this value to 1.

Added in version 0.2.2.

quality_static: int = 80#: The quality of the static image thumbnail.

Added in version 0.2.1.

quality_animated: int = 50#: The quality of the animated image thumbnail.

Added in version 0.2.1.

save_kwargs: dict[str, int]#

The parameters passed to save function for the thumbnail image.

See the Pillow documentation for more information: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#webp-saving

Note

The quality of the saved image is suggested to be set by the quality_static and quality_animated attributes separately.

to_dict() → dict[source]#: Convert the configuration to a dictionary.

class myst_sphinx_gallery.config.GalleryConfig(examples_dirs: ~pathlib.Path | str | list[~pathlib.Path | str] | None = None, gallery_dirs: ~pathlib.Path | str | list[~pathlib.Path | str] | None = None, root_dir: ~pathlib.Path | str | None = None, thumbnail_strategy: ~typing.Literal['first', 'last'] = 'last', notebook_thumbnail_strategy: ~typing.Literal['markdown', 'code'] = 'markdown', default_thumbnail_file: ~pathlib.Path | str | None = None, thumbnail_config: ~myst_sphinx_gallery.config.ThumbnailConfig = <factory>, remove_thumbnail_after_build: bool = True, base_gallery: bool = False, target_prefix: str = 'example_', toc_tree: ~myst_sphinx_gallery.grid.TocTree = <factory>, grid: ~myst_sphinx_gallery.grid.Grid = <factory>, grid_item_card: ~myst_sphinx_gallery.grid.GridItemCard = <factory>)[source]#

Configurations to generate the gallery from examples.

Examples

if you are using this configuration in conf.py, you can initialize the configuration as follows:

from pathlib import Path
from myst_sphinx_gallery import GalleryConfig

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

examples_dirs: Path | str | list[Path | str] | None = None#

The directories containing the example scripts. There must be a GALLERY_HEADER.rst file in each of these directories.

Note

The paths are relative to the root directory root_dir.
If a list of paths is provided, the number of paths must match the number of paths in gallery_dirs.

Changed in version 0.3.0: Can be None for pure configuration, which not generating the gallery.

gallery_dirs: Path | str | list[Path | str] | None = None#

The directories where the gallery output will be saved.

Note

The paths are relative to the root directory root_dir.
If a list of paths is provided, the number of paths must match t number of paths in examples_dirs.

Changed in version 0.3.0: Can be None for pure configuration, which not generating the gallery.

root_dir: Path | str | None = None#: The root directory for any relative paths in this configuration.

Tip

You can use the __file__ variable to get the path to the current file if you are using this configuration in conf.py. For example, Path(__file__).parent is the root directory in this case.

Changed in version 0.3.0: Can be None for pure configuration, which not generating the gallery.

thumbnail_strategy: Literal['first', 'last'] = 'last'#: The strategy to use for selecting the thumbnail image for each example if multiple images are candidates.

notebook_thumbnail_strategy: Literal['markdown', 'code'] = 'markdown'#: The strategy to use for selecting the thumbnail image for jupyter notebook, if both markdown and code cells contain images.

default_thumbnail_file: Path | str | None = None#: The path to the default thumbnail image file. If no thumbnail image is found for an example, this image will be used. If None, a default thumbnail image in this package will be used.

thumbnail_config: ThumbnailConfig#: The configuration for the thumbnail image.

remove_thumbnail_after_build: bool = True#: Whether to remove the thumbnail image after building the gallery.

base_gallery: bool = False#: Whether the examples are a base gallery.

Tip

You can use the base-gallery directive alternatively.

Added in version 0.3.0.

target_prefix: str = 'example_'#: The prefix to use for the target names of the gallery files.

Added in version 0.2.1.

toc_tree: TocTree#: A instance of TocTree class to create a table of content for gallery. Currently, no additional options are supported.

Changed in version 0.3.0: This parameter is not suggested to be used by user. It will only be internally used by program.

grid: Grid#: A instance of Grid class for gallery. You can customize the grid layout using this configuration.

Changed in version 0.3.0: This parameter is not suggested to be used by user. It will only be internally used by program.

grid_item_card: GridItemCard#: A instance of GridItemCard class for gallery. You can customize he grid item card using this configuration.

Changed in version 0.3.0: This parameter is not suggested to be used by user. It will only be internally used by program.

abs_path(path: Path | str) → Path[source]#: Convert a path to an absolute path using the root directory.

to_dict() → dict[source]#: Convert the configuration to a dictionary.

class myst_sphinx_gallery.config.GalleryThumbnailConfig(thumbnail_strategy: ~typing.Literal['first', 'last'] = 'last', notebook_thumbnail_strategy: ~typing.Literal['markdown', 'code'] = 'markdown', default_thumbnail_file: ~pathlib.Path | str | None = None, thumbnail_config: ~myst_sphinx_gallery.config.ThumbnailConfig = <factory>)[source]#

Configurations to generate the gallery from examples.

Examples

if you are using this configuration in conf.py, you can initialize the configuration as follows:

from pathlib import Path
from myst_sphinx_gallery import GalleryConfig

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

thumbnail_strategy: Literal['first', 'last'] = 'last'#: The strategy to use for selecting the thumbnail image for each example if multiple images are candidates.

notebook_thumbnail_strategy: Literal['markdown', 'code'] = 'markdown'#: The strategy to use for selecting the thumbnail image for jupyter notebook, if both markdown and code cells contain images.

default_thumbnail_file: Path | str | None = None#: The path to the default thumbnail image file. If no thumbnail image is found for an example, this image will be used. If None, a default thumbnail image in this package will be used.

thumbnail_config: ThumbnailConfig#: The configuration for the thumbnail image.

to_dict() → dict[source]#: Convert the configuration to a dictionary.