A Sphinx extension that builds galleries of examples from any set of myst-style markdown/notebook or rst files.
Project description
Introduction
MyST Sphinx Gallery is a Sphinx extension that allows you to build galleries of examples from Jupyter Notebooks (.ipynb
), Markdown (.md
) or reStructuredText (.rst
) files. It works with MyST
Ecosystem, including MyST-parser and MyST-NB, to render markdown or jupyter notebooks in Sphinx documentation.
Highlight Features
- Convenient to use - You can easily generate a gallery of examples from
your Jupyter Notebooks, Markdown, or reStructuredText files. It works with
MyST
Ecosystem, including MyST-parser and MyST-NB, to render markdown or jupyter notebooks in Sphinx documentation. - Customizable - You can customize the gallery configuration, such as the strategy to select the thumbnail, the gallery layout, and the gallery directory.
Documentation
The detailed documentation is available at: https://myst-sphinx-gallery.readthedocs.io/en/latest/
Quick Start
[!NOTE] The quick start guide here is a brief introduction to the MyST Sphinx Gallery extension. More detailed Quick Start guide is available at: Quick Start.
Installation
MyST Sphinx Gallery is a Python package, and requires Python >= 3.8
. You can install the latest release using pip
from the PyPI:
pip install myst_sphinx_gallery
Configure and usages
To use MyST Sphinx Gallery, you need to add the following code to the Sphinx conf.py
file:
from pathlib import Path
from myst_sphinx_gallery import GalleryConfig, generate_gallery
generate_gallery(
GalleryConfig(
examples_dirs="../../examples",
gallery_dirs="auto_examples",
root_dir=Path(__file__).parent,
notebook_thumbnail_strategy="code",
)
)
[!NOTE] You can generate multiple galleries by proper configuration in the
conf.py
file. For more details, please refer to the Configure multiple galleries.
Construct the examples folder
To generate the gallery, you need to create a well-structured examples folder. The detailed documentation of structuring files for gallery is available at: Structuring files for Gallery and Controlling Examples Order .
Select the thumbnail for an example file
- one image - If there only one image in an example file, no additional configuration is needed, and that image will be used as the gallery thumbnail.
- multiple images - If there are multiple figures in an example file, you can specify the strategy to determine which thumbnail will be used for the gallery. The following strategies are supported:
- alt - If the alt attribute of an image/figure is set to gallery_thumbnail, that image/figure will be used as the gallery thumbnail for this file.
- first/last - If there are multiple images that can be used as the gallery thumbnail, the first/last image will be selected. You can specify the strategy by setting the thumbnail_strategy in the configuration file. The default value is first.
- code/markdown - For Jupyter notebook files, both markdown and code cells can contain images. You can specify the strategy by setting the notebook_thumbnail_strategy in the configuration file. The default value is code.
- no image - If no image/figure is found, the default thumbnail will be used.
More details can be found in the Thumbnail Strategies.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for myst_sphinx_gallery-0.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3f3009812829db9794a5cefc96554c5ffef7f2f20a3c19490eaedf0f83e7ee94 |
|
MD5 | 53caed0f992b0df47ce75732f131366c |
|
BLAKE2b-256 | c8827a3e8cf7759a373fa2e244742b28630b166d0f726e8bacf8f8cc12ca1728 |
Hashes for myst_sphinx_gallery-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0305404c3a3b5cebeda6e66a2f8556cfa4bf205758eae80dada71f8948044c0 |
|
MD5 | f063438decd1a9db277ba74d993f1012 |
|
BLAKE2b-256 | b0b5ce8290a5812f2418bfdbceafbbb3a5f6924ce2c999fa1cf7569b8df88b8c |