Structuring files for Gallery

MyST Sphinx Gallery can help you to generate a gallery for a well-structured examples folder.

Basic rules

The file structure for the examples folder should follow the following rules:

1. A GALLERY_HEADER.rst file in the root folder of examples to display the gallery title and description.

2. Sub-folders with a GALLERY_HEADER.rst file in them to determine the sections in the gallery. This file contains title and description for the section.

3. Example files in the sub-folders. The example files can be jupyter notebooks (.ipynb), markdown (.md) or reStructuredText (.rst) files.

Important

• The whole sub-folder will be ignored if it does not have the GALLERY_HEADER.rst file in it.

• The GALLERY_HEADER.rst file will be converted to the index.rst for the gallery. Therefore, you need to use index rather that GALLERY_HEADER as the file name when cross-referencing.

Overview of the file structure

For example, if you have the following file structure in your Python project:

.
├── doc
│   ├── conf.py
│   ├── index.rst
│   ├── user_guide.rst
│   ├── api.rst
|   ├── make.bat
│   └── Makefile
├── python_module
│   ├── __init__.py
│   └── mod.py
└── examples
    ├── GALLERY_HEADER.rst
    ├── 02-basic
    │    ├── GALLERY_HEADER.rst
    │    ├── 01-basic-example3.rst
    │    ├── 02-basic-example2.md
    │    └── 03-basic-example1.ipynb
    └── 01-advanced
        ├── GALLERY_HEADER.rst
        ├── 01-advanced-example3.rst
        ├── 02-advanced-example2.md
        └── 03-advanced-example1.ipynb

conf.py

In this case, you can add the following configuration to the Sphinx conf.py file:

conf.py

myst_sphinx_gallery_config = GalleryConfig(
    examples_dirs="../examples",
    gallery_dirs="auto_examples",
    root_dir=Path(__file__).parent,
    ...
)

The examples folder will be converted to the following gallery in the doc:

.
└── doc
    ├── auto_examples(index)
    │    ├── advanced(index)
    │    │    ├── advanced-example3
    │    │    ├── advanced-example2
    │    │    └── advanced-example1
    │    └── basic(index)
    │         ├── basic-example3
    │         ├── basic-example2
    │         └── basic-example1
    ├── conf.py
    ├── index.rst
    ├── user_guide.rst
    ├── api.rst
    ├── make.bat
    └── Makefile

Note

The number prefix in the directory/file names will be removed in the output gallery. See Controlling Examples Order for more details.

To refer to the gallery in the documentation, you can directly add the generated gallery index to the toctree directive in the index.rst file:

index.rst

.. toctree::
    :maxdepth: 2
    :caption: Constants:

    user_guide
    auto_examples/index
    api