myst_sphinx_gallery.gallery#

A module for managing the gallery of examples.

Functions

`generate_gallery`(gallery_config)	Generate the gallery from the examples directory.
`write_index_file`(header_file, index_file, ...)	Write/Append string into a gallery header file.

Classes

`ExampleConverter`(example_file, examples_dir, ...)	A class to convert an example to a standardized example file.
`GalleryGenerator`(examples_dir, gallery_dir, ...)	A class to generate the gallery for a folder.
`SectionGenerator`(header_file, examples_dir, ...)	A class to generate the gallery section for a subfolder.

myst_sphinx_gallery.gallery.generate_gallery(gallery_config: GalleryConfig | dict) → None[source]#

Generate the gallery from the examples directory.

Parameters:: gallery_config (GalleryConfig | dict) – The gallery configuration.

class myst_sphinx_gallery.gallery.GalleryGenerator(examples_dir: Path, gallery_dir: Path, config: GalleryConfig)[source]#

A class to generate the gallery for a folder.

property folders: list[Path]#: Folders that contain example files.

property header_file: Path#: The path to the input example header file.

property index_file: Path#: The path to the output gallery index file.

property target_str: str#: The target string in the gallery file used to link to the example file.

property toc: str#: The table of contents string for the gallery.

property sections: str#: The sections for the gallery.

property toc_tree: TocTree#: The table of contents tree options for the gallery.

property grid: Grid#: The grid options for the gallery.

property grid_item_card: GridItemCard#: The grid item card options for the gallery.

add_toc_item(section_index_file: str) → None[source]#: Add a toc item for the gallery.

add_section_item(title: str, section_grid: str) → None[source]#: Add a section item to the gallery.

convert_to_index_file() → None[source]#: Convert the gallery header file.

convert() → None[source]#: Convert the examples to gallery.

class myst_sphinx_gallery.gallery.SectionGenerator(header_file: Path, examples_dir: Path, gallery_dir: Path, config: GalleryConfig)[source]#

A class to generate the gallery section for a subfolder.

property config: GalleryConfig#: The gallery configuration.

property header_file: Path#: Path to the gallery header file.

property index_file: Path#: Path to the output gallery header file.

property target_str: str#: The target string in the gallery file used to link to the example file.

property example_files: list[Path]#: Path to the example files in a same subfolder.

property toc: str#: The table of contents for gallery section.

property section_grid: str#: The grid for the gallery section.

property toc_tree: TocTree#: The table of contents options for gallery section.

property grid: Grid#: The grid options for gallery section.

property grid_item_card: GridItemCard#: The grid item card options for gallery section.

add_grid_card(grid_item_card: str) → str[source]#: Add a grid card for the gallery section grid.

add_example_to_toc(gallery: str) → None[source]#: Add a example to the table of contents of section.

convert_section_header_file() → None[source]#

Convert the header file of the subfolder to a standardized header file.

New header file will contain toc and grid cards for the gallery section.

convert() → None[source]#: Convert the example files to standardized example files.

class myst_sphinx_gallery.gallery.ExampleConverter(example_file: Path | str, examples_dir: Path | str, gallery_dir: Path | str, config: GalleryConfig, thumbnail_location: Literal['gallery', 'parent'] = 'gallery', save_thumbnail: bool = True)[source]#

A class to convert an example to a standardized example file.

notebook, md, rst are all supported.

property config: GalleryConfig#: The gallery configuration.

property file_type: Literal['notebook', 'markdown', 'rst']#: The file type of the example file.

property relative_path: str#: The relative path of the example file.

property example_file: Path#: Path to the input example file.

property gallery_file: Path#: Path to the output gallery file.

property grid_item_card: str#: The grid item card for the gallery.

property target_str: str#: The target string in the gallery file used to link to the example file.

property target_ref: str#: The target reference for the example file.

property gallery_thumb: Path#: Path to the thumbnail image for the gallery.

property default_thumb: Path#: Path to the default thumbnail image.

property thumb_dir: Path#: Path to the thumbnail directory for the example.

property no_image_thumb: Path#: Path to the no image thumbnail.

thumb_file_rel(thumb_file: Path) → str[source]#: Relative path to the thumbnail image for the example.

property thumb_idx: int#: The index of the thumbnail image to use.

convert() → None[source]#: Convert the example file to a standardized example file.

myst_sphinx_gallery.gallery.write_index_file(header_file: Path, index_file: Path, append_str: str, prepend_str: str = '') → None[source]#

Write/Append string into a gallery header file.

Parameters:

header_file (Path) – The path to the example header file.
index_file (Path) – The path to the output gallery index file.
append_str (str) – The string to append to the gallery header file.
prepend_str (str, optional) – The string to prepend to the gallery header file.