myst_sphinx_gallery.utils#

Utility functions for the myst-sphinx-gallery package.

Functions

`abs_path`(path, root_dir[, method])	Convert a relative path to an absolute path.
`default_thumbnail`()	Return the path to the default thumbnail image.
`ensure_dir_exists`(dir_path)	Ensure that the directory exists.
`extract_title_and_tooltip`(file_path)	Extract the title and tooltip from a file.
`file_in_folder`(file_path, folder_path)	Check if the file is in the folder.
`gallery_static_path`()	Return the path to the CSS file.
`get_base_gallery_items`(content[, style])	Get the sub-gallery items from the given content.
`get_rst_title`([file_path, content])	Get the title of a reStructuredText file.
`load_nb_markdown`(nb_file)	Load the markdown content from a Jupyter notebook file as string.
`parse_files_without_suffix`(path)	Parse the files without the suffix.
`print_run_time`(func)	Print the run time of a function.
`remove_num_prefix`(header_file)	Remove the number prefix from the example file/dir.
`remove_special_chars`(input_string)	Remove special characters from a string.
`safe_remove_dir`(dir_path)	Remove a directory if it exists.
`safe_remove_file`(file)	Remove a file if it exists.
`to_section_title`(title)	Convert a title to a reStructuredText section title.

myst_sphinx_gallery.utils.ensure_dir_exists(dir_path: Path) → None[source]#

Ensure that the directory exists.

dir_pathPath: The path to the directory.

myst_sphinx_gallery.utils.safe_remove_file(file: Path) → None[source]#: Remove a file if it exists.

myst_sphinx_gallery.utils.safe_remove_dir(dir_path: Path) → None[source]#: Remove a directory if it exists.

myst_sphinx_gallery.utils.abs_path(path: Path | str, root_dir: Path | str, method: Literal['resolve', 'rglob'] = 'resolve') → Path[source]#

Convert a relative path to an absolute path.

Parameters:

path (Path | str) – The relative path.
root_dir (Path | str) – The root directory.
method (Literal["resolve", "rglob"], optional) –
The method to use for converting the path, by default “resolve”.
- resolve: Use the resolve method of the Path class to convert the path.
- rglob: try to find a matched path in the root directory using rglob.

Returns:

The absolute path.

Return type:

Path

myst_sphinx_gallery.utils.parse_files_without_suffix(path: Path | str) → set[Path][source]#

Parse the files without the suffix.

Support wildcard in the path name to match multiple files.

Parameters:: path (Path | str) – The path without the suffix.

myst_sphinx_gallery.utils.get_rst_title(file_path: Path | str | None = None, content: str | None = None) → str | None[source]#

Get the title of a reStructuredText file.

Either the file path or the content of the file should be provided.

Parameters:

file_path (Path, optional) – The path to the reStructuredText file, by default None.
content (str, optional) – The content of the reStructuredText file, by default None. If not provided, the content is read from the file.

myst_sphinx_gallery.utils.extract_title_and_tooltip(file_path: Path | str) → tuple[str, str][source]#

Extract the title and tooltip from a file.

The file can be either a reStructuredText or a markdown/notebook file.

Parameters:: file_path (Path) – The path to the file.
Returns:: title, tooltip – The title and tooltip in the string format.
Return type:: str, str

myst_sphinx_gallery.utils.get_base_gallery_items(content: str, style: Literal['rst', 'md'] = 'rst') → list[str][source]#

Get the sub-gallery items from the given content.

Parameters:

content (str) – The reStructuredText content.
style (Literal["rst", "md"], optional) – The style of the content, by default “rst”.

Returns:

items – The items in the sub-gallery.

Return type:

list[str]

myst_sphinx_gallery.utils.to_section_title(title: str) → str[source]#: Convert a title to a reStructuredText section title.

myst_sphinx_gallery.utils.remove_num_prefix(header_file: Path) → tuple[str, str][source]#: Remove the number prefix from the example file/dir.

myst_sphinx_gallery.utils.file_in_folder(file_path: Path | str, folder_path: Path | str) → bool[source]#

Check if the file is in the folder.

Subdirectories are also considered.

Parameters:

file_path (Path | str) – The path to the file.
folder_path (Path | str) – The path to the folder.

Returns:

True if the file is in the folder, False otherwise.

Return type:

bool

myst_sphinx_gallery.utils.print_run_time(func: callable) → callable[source]#: Print the run time of a function.

myst_sphinx_gallery.utils.load_nb_markdown(nb_file: Path) → str[source]#: Load the markdown content from a Jupyter notebook file as string.

myst_sphinx_gallery.utils.gallery_static_path() → Path[source]#: Return the path to the CSS file.

myst_sphinx_gallery.utils.default_thumbnail() → Path[source]#: Return the path to the default thumbnail image.

myst_sphinx_gallery.utils.remove_special_chars(input_string: str) → str[source]#

Remove special characters from a string.

Special characters are typically are used for styling content. This function is useful for removing special characters from the title and tooltip.