myst_sphinx_gallery.directives#

Sphinx directives to generate galleries.

Functions

`create_card_node`(arguments, options, ...)	Create a card node for the grid.
`create_card_title_node`(title[, options, ...])	Create a title node for the card.
`create_component`(name[, classes, rawtext, ...])	Create a container node for a design component.
`create_grid_node`(grid[, sphinx_directive])	Create a container node for the grid.
`create_title_node`(title)	Create a title node for the section.
`ensure_config`(config)	Ensure that the gallery config is set.
`format_option`(option)	Format the option for the directive.
`row_columns_option`(argument)	Validate the number of columns (out of 12) a grid row will have.

Classes

`BaseGallery`(name, arguments, options, ...)	Directive to create a `base-gallery` with a toctree-like structure.
`CardDirectiveWrapper`(name, arguments, ...)	A wrapper of the sphinx-design card directive to add gallery features.
`GalleryABC`(name, arguments, options, ...)	An abstract class for the gallery directives.
`GalleryDirective`(name, arguments, options, ...)	Directive to create a `gallery` with a toctree-like structure.
`RefGalleryDirective`(name, arguments, ...)	Directive to create a referenced gallery using `ref-gallery` directive.
`card_col_node`([rawsource])	A container node for a card column.

class myst_sphinx_gallery.directives.GalleryABC(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

An abstract class for the gallery directives.

run() → list[Node][source]#: Generate the gallery nodes.

create_cards_for_row_node(entry_files: str, row_node: Node, save_thumbnail: bool) → Node[source]#: Create the cards for the row node.

create_toctree() → list[Node][source]#: Generate the toctree node for the sub-gallery.

parse_file_gallery_config(file_path: str) → GalleryConfig[source]#: Parse the gallery config for give file.

class myst_sphinx_gallery.directives.RefGalleryDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

Directive to create a referenced gallery using ref-gallery directive.

This gallery will not create toctree entries for the examples. The examples in this gallery are all referenced from other galleries.

option_spec = {'tooltip': <function flag>}#: Mapping of option names to validator functions.

has_content = True#: May the directive have content?

run() → list[Node][source]#: Generate the grid node for the ref-gallery directive.

gallery_example() → None[source]#: Serve as an example for the ref-gallery directive in code docs.

Rst Image Directive

../../examples/alt/rst%20image.html

first strategy

../../examples/first_last/first.html

code | first strategy

../../examples/code_markdown/first%20code.html

class myst_sphinx_gallery.directives.BaseGallery(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

Directive to create a base-gallery with a toctree-like structure.

option_spec = {'caption': <function unchanged>, 'tooltip': <function flag>}#: Mapping of option names to validator functions.

has_content = True#: May the directive have content?

run() → list[Node][source]#: Generate the grid node for the base-gallery directive.

class myst_sphinx_gallery.directives.GalleryDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

Directive to create a gallery with a toctree-like structure.

Hint

The items in this gallery are the files that contain the base-gallery directives.
The title of each file of items will be used as the section title in the gallery.
The * wildcard can be used for matching multiple files.

option_spec = {'caption': <function unchanged>, 'tooltip': <function flag>}#: Mapping of option names to validator functions.

has_content = True#: May the directive have content?

run() → list[Node][source]#: Generate the grid and toctree nodes for the gallery directive.

myst_sphinx_gallery.directives.ensure_config(config: GalleryConfig | GalleryThumbnailConfig | dict | None) → GalleryConfig[source]#: Ensure that the gallery config is set.

myst_sphinx_gallery.directives.format_option(option: dict) → dict[source]#: Format the option for the directive.

myst_sphinx_gallery.directives.row_columns_option(argument: str | None) → list[str][source]#

Validate the number of columns (out of 12) a grid row will have.

One or four integers (for “xs sm md lg”) between 1 and 12 (or ‘auto’).

class myst_sphinx_gallery.directives.CardDirectiveWrapper(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

A wrapper of the sphinx-design card directive to add gallery features.

Modifications include:

Adding myst-sphinx-gallery classes to the card.
Adding loading=”lazy” to the image tags.
Removing some unnecessary components.

classmethod create_card(arguments: list, options: dict, sphinx_directive: SphinxDirective, offset: int = 0) → Node[source]#: Run the directive.

myst_sphinx_gallery.directives.create_grid_node(grid: Grid, sphinx_directive: SphinxDirective | None = None) → tuple[Node, Node][source]#

Create a container node for the grid.

Parameters:

sphinx_directive (SphinxDirective) – The directive instance.
grid (Grid) – The Grid instance which contains the grid options.

Returns:

The grid and row nodes.

Return type:

tuple[nodes.Node, nodes.Node]

myst_sphinx_gallery.directives.create_card_node(arguments: list, options: dict, sphinx_directive: SphinxDirective) → Node[source]#

Create a card node for the grid.

Parameters:

arguments (list) – The arguments for the card.
options (dict) – The options for the card.
sphinx_directive (SphinxDirective) – The directive instance.

myst_sphinx_gallery.directives.create_title_node(title: str) → Node[source]#: Create a title node for the section.

myst_sphinx_gallery.directives.create_card_title_node(title: str, options: dict | None = None, sphinx_directive: SphinxDirective | None = None) → Node[source]#

Create a title node for the card.

Parameters:

title (str) – The title for the card.
sphinx_directive (SphinxDirective) – The directive instance.
options (dict, optional) – The options for the title node.

myst_sphinx_gallery.directives.create_component(name: str, classes: Sequence[str] = (), *, rawtext: str = '', children: Sequence[Node] = (), node: Literal['card_col'] | None = None, **attributes) → container[source]#: Create a container node for a design component.

class myst_sphinx_gallery.directives.card_col_node(rawsource='', *children, **attributes)[source]#: A container node for a card column.