Configuration 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.

Hint

Those two variables are optional and can be omitted if you don’t need to customize the behavior of MyST Sphinx Gallery.

myst_sphinx_gallery_config

This variable has two usages:

1. It can be used to generate galleries when providing the examples and galleries dictionaries.

2. It will serve as a global configuration for all examples using gallery directives. In this case, examples and galleries dictionaries can be None.

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.

Hint

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

Specify the thumbnail selection strategies

myst_sphinx_gallery_config can be used to specify the thumbnail selection strategies for the gallery. More details can be found in the Thumbnail Strategies

Customizing the thumbnail style

myst_sphinx_gallery_config can be used to customize the thumbnail style. More details can be found in the Customizing thumbnail style

Remove thumbnail after build

By default, MyST Sphinx Gallery will clean up the thumbnail files after the build is complete. You can disable this behavior by setting remove_thumbnail_after_build to False in your myst_sphinx_gallery_config variable.

This can be useful if you are frequently re-building the documentation to save building time.

conf.py

from myst_sphinx_gallery import GalleryConfig

myst_sphinx_gallery_config = GalleryConfig(
    ...,  # other configurations
    remove_thumbnail_after_build=False,
)

myst_sphinx_gallery_files_config

This variable is used to override the global configuration for individual files. It should be a instance of FilesConfig class.

There are two parameters that should be set in this class:

• named_config : a dictionary of named configurations. The keys of the dictionary are the names of the configurations and the values are instances of GalleryThumbnailConfig class.

• files_config : a dictionary of config name and corresponding file paths that can be used to apply the same configuration to multiple files.

conf.py

 from myst_sphinx_gallery import FilesConfig, GalleryThumbnailConfig

myst_sphinx_gallery_files_config = FilesConfig(
    named_config={
        "first_md": GalleryThumbnailConfig(
            thumbnail_strategy="first", notebook_thumbnail_strategy="markdown"
        ),
        "first_code": GalleryThumbnailConfig(
            thumbnail_strategy="first", notebook_thumbnail_strategy="code"
        ),
        "last_md": GalleryThumbnailConfig(
            thumbnail_strategy="last", notebook_thumbnail_strategy="markdown"
        ),
        "last_code": GalleryThumbnailConfig(
            thumbnail_strategy="last", notebook_thumbnail_strategy="code"
        ),
    },
    files_config={
        "first_code": [
            "examples/code_markdown/first code.ipynb",
            ],
        "last_code": [
            "examples/code_markdown/last code.ipynb",
            ],
        "first_md": [
            "examples/code_markdown/first markdown.ipynb",
            "examples/first_last/first.rst",
            ],
        "last_md": [
            "examples/code_markdown/last markdown.ipynb",
            "examples/first_last/last.rst",
            ],
    },
)