merge from dev

.github/workflows/pre-commit.yml

@@ -0,0 +1,18 @@
+name: pre-commit
+
+#on:
+#  pull_request:
+#  push:
+#    branches: [master, dev]
+on:
+    pull_request:
+    # to trigger workflow manually from actions-tab
+    workflow_dispatch:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+    - uses: pre-commit/[email protected]

.github/workflows/tests.yml

@@ -0,0 +1,51 @@
+
+name: Tests
+
+on:
+   pull_request:
+   # to trigger workflow manually from actions-tab
+   workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        # set operating systems to test
+        os: [ubuntu-latest]
+        # set python versions to test
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    name: tests ${{ matrix.os }}  ${{ matrix.python-version }}
+    steps:
+      # checkout repository
+      - uses: actions/checkout@v3
+      # install miniconda environment
+
+      - uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: tests/tests_env.yml
+          init-shell: >-
+            bash
+          cache-environment: true
+          post-cleanup: 'all'
+          create-args: >-
+            python=${{ matrix.python-version }}
+      - name: Test with pytest
+        shell: bash -l {0}
+        run: |
+          pip install -e .[test]
+          python -m pytest -v --cov=myst_sphinx_gallery --cov-report=xml
+      - name: Upload Image Comparison Artefacts
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-coverage-report
+          path: img_comparison_results
+      - name: Upload coverage to Codecov
+        uses: codecov/[email protected]
+        with:
+          env_vars: ${{ matrix.os }}, ${{ matrix.python-version }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true
+          verbose: true

MANIFEST.in

@@ -1 +1 @@
-include myst_sphinx_gallery/_static/no_image.png
+include myst_sphinx_gallery/_static/no_image.png

README.md

@@ -0,0 +1,44 @@
+# MyST Sphinx Gallery
+
+MyST Sphinx Gallery is a Sphinx extension that builds a Sphinx Gallery from MyST Markdown/Notebook or RST files.
+
+![gallery_example](docs/source/_static/gallery_example.png)
+
+## Documentation
+
+The detailed documentation is available at: [https://myst-sphinx-gallery.readthedocs.io/en/latest/](https://myst-sphinx-gallery.readthedocs.io/en/latest/)
+
+## Quick Start
+
+> [!NOTE] The quick start guide in README is a brief introduction to the MyST Sphinx Gallery extension. The full documentation of "Quick Start" is available at: [Quick Start](https://myst-sphinx-gallery.readthedocs.io/en/latest/user_guide/quick_start.html).
+
+## Installation
+
+**MyST Sphinx Gallery** is a Python package, and requires `Python >= 3.8`. You can install the latest release using `pip` from the PyPI:
+
+```bash
+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:
+
+```python
+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 [Multiple Galleries](https://myst-sphinx-gallery.readthedocs.io/en/latest/user_guide/multi_galleries.html).
+
+## 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](https://myst-sphinx-gallery.readthedocs.io/en/latest/user_guide/example_structure.html).

docs/source/api/index.rst

@@ -4,7 +4,7 @@
 API Reference
 =============
 
-This section contains the API reference documentation for the MyST Sphinx Gallery extension. 
+This section contains the API reference documentation for the MyST Sphinx Gallery extension.
 
 .. toctree::
    :maxdepth: 2

docs/source/user_guide/order.rst

@@ -37,4 +37,3 @@ will be displayed in the gallery as:
          ├── basic-example3
          ├── basic-example2
          └── basic-example1
-

examples/00-alt/rst.rst

@@ -20,15 +20,15 @@ image directive with ``alt`` set to ``gallery_thumbnail``
 
 .. code-block:: rst
 
-    .. image:: /_static/bar_colors.png
+    .. image:: /_static/example_basics.gif
         :align: center
         :alt: gallery_thumbnail
 
 .. note::
 
     This image directive has set the ``alt`` attribute to ``gallery_thumbnail``. Therefore, This image will be used as the thumbnail for the gallery.
 
-.. image:: /_static/bar_colors.png
+.. image:: /_static/example_basics.gif
     :align: center
     :alt: gallery_thumbnail
 

examples/01-alt_order/01-rst_order.rst

@@ -21,15 +21,15 @@ image directive with ``alt`` set to ``gallery_thumbnail``
 .. code-block:: rst
     :emphasize-lines: 3
 
-    .. image:: /_static/bar_colors.png
+    .. image:: /_static/example_basics.gif
         :align: center
         :alt: gallery_thumbnail
 
 .. note::
 
     This image directive has set the ``alt`` attribute to ``gallery_thumbnail``. Therefore, This image will be used as the thumbnail for the gallery.
 
-.. image:: /_static/bar_colors.png
+.. image:: /_static/example_basics.gif
     :align: center
     :alt: gallery_thumbnail
 

examples/code_markdown/GALLERY_HEADER.rst

@@ -3,5 +3,3 @@ Code/Markdown Strategy for Notebooks
 ====================================
 
 This section tests selecting the thumbnail image from markdown or code cells in a Jupyter notebook.
-
-

examples/default/GALLERY_HEADER.rst

@@ -1,5 +1,5 @@
 =====================
-Default Gallery Image 
+Default Gallery Image
 =====================
 
-This section tests the cases where the example files do not have any images in them. The gallery should use the default image in this case.
+This section tests the cases where the example files do not have any images in them. The gallery should use the default image in this case.

examples/default/no_image.rst

@@ -3,6 +3,6 @@ Default Gallery Image
 =====================
 
 
-.. note:: 
+.. note::
 
-    This file does not contain any images. Therefore, the default gallery image will be used.
+    This file does not contain any images. Therefore, the default gallery image will be used.

myst_sphinx_gallery/__init__.py

@@ -6,6 +6,7 @@
 
 from .config import GalleryConfig
 from .gallery import generate_gallery
+from .grid import Grid, GridItemCard, TocTree
 
 # dev versions should have "dev" in them, stable should not.
 # doc/conf.py makes use of this to set the version drop-down.

myst_sphinx_gallery/config.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Literal
 
+from .grid import Grid, GridItemCard, TocTree
+from .io_tools import abs_path
+
 
 @dataclass
 class GalleryConfig:
@@ -31,7 +34,7 @@ class GalleryConfig:
     #:
     #: .. note::
     #:
-    #:    1. If the paths are relative, ``root_dir`` must be provided.
+    #:    1. The paths is relative to the root directory.
     #:    2. If a list of paths is provided, the number of paths must match
     #:       the number of paths in ``gallery_dirs``.
     examples_dirs: Path | str | list[Path | str]
@@ -40,22 +43,18 @@ class GalleryConfig:
     #:
     #: .. note::
     #:
-    #:    1. If the paths are relative, ``root_dir`` must be provided.
+    #:    1. The paths is relative to the root directory.
     #:    2. If a list of paths is provided, the number of paths must match the
     #:       number of paths in ``example_dirs``.
     gallery_dirs: Path | str | list[Path | str]
 
     #: The root directory for any relative paths in this configuration.
     #:
-    #: .. important::
-    #:    This is must be provided if the paths in ``examples_dirs`` and
-    #:    ``gallery_dirs`` are relative.
-    #:
     #: .. tip::
     #:    You can use the ``__file__`` variable to get the path to the
     #:    current file if you are using this configuration in ``conf.py``.
     #:    For example, ``Path(__file__).parent`` is the root directory in this case.
-    root_dir: Path | str | None = None
+    root_dir: Path | str
 
     #: The strategy to use for selecting the thumbnail image for each example
     #: if multiple images are candidates.
@@ -70,6 +69,18 @@ class GalleryConfig:
     #: If None, a default thumbnail image in this package will be used.
     default_thumbnail_file: Path | str | None = None
 
+    #: A instance of the TocTree class to create a table of content for the
+    #: gallery images. Currently, no additional options are supported.
+    toc_tree: TocTree = field(default_factory=TocTree)
+
+    #: The grid configuration for the gallery images. You can customize the
+    #: grid layout using this configuration.
+    grid: Grid = field(default_factory=Grid)
+
+    #: The grid item card configuration for the gallery images. You can customize
+    #: the grid item card using this configuration.
+    grid_item_card: GridItemCard = field(default_factory=GridItemCard)
+
     def __post_init__(self):
         if isinstance(self.examples_dirs, (Path, str)):
             self.examples_dirs = [self.examples_dirs]
@@ -81,25 +92,20 @@ def __post_init__(self):
                 "The number of paths in examples_dirs and gallery_dirs must match"
             )
 
-        if self.root_dir is None and any(
-            Path(d).is_absolute() for d in self.examples_dirs + self.gallery_dirs
-        ):
-            raise ValueError(
-                "root_dir must be provided if examples_dirs or gallery_dirs are absolute paths"
-            )
-
         self.examples_dirs = [self.abs_path(d) for d in self.examples_dirs]
         self.gallery_dirs = [self.abs_path(d) for d in self.gallery_dirs]
 
         if self.default_thumbnail_file is not None:
             self.default_thumbnail_file = self.abs_path(self.default_thumbnail_file)
 
+        # clear the items in toc_tree, grid, and grid_item_card, keeping the options
+        self.toc_tree = self.toc_tree.copy()
+        self.grid = self.grid.copy()
+        self.grid_item_card = self.grid_item_card.copy()
+
     def abs_path(self, path: Path | str) -> Path:
         """Convert a path to an absolute path using the root directory"""
-        path = Path(path)
-        if not path.is_absolute():
-            path = (self.root_dir / path).resolve()
-        return path
+        return abs_path(path, self.root_dir)
 
     def to_dict(self):
         """Convert the configuration to a dictionary"""