==================================
What’s new in 0.2.0 (Aug 13, 2024)
==================================


Setup by extension
------------------

Now you can add the ``myst_sphinx_gallery`` extension to the ``extensions``
list and specify the ``myst_sphinx_gallery_config`` variable in the
``conf.py`` file to configure the gallery.

.. code-block:: python
    :caption: conf.py
    :emphasize-lines: 1, 9

    extensions = [
        ...,  # other extensions
        "myst_sphinx_gallery",
    ]

    from pathlib import Path
    from myst_sphinx_gallery import GalleryConfig

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

The parameters in the ``myst_sphinx_gallery_config`` variable will be used to
configure the gallery. Available parameters can be found in the
:class:`~myst_sphinx_gallery.GalleryConfig` class.

.. tip::

    - The ``myst_sphinx_gallery_config`` variable can either be a instance of :class:`~myst_sphinx_gallery.GalleryConfig` class or a dictionary with the same keys as the :class:`~myst_sphinx_gallery.GalleryConfig` class.
    - The :class:`~myst_sphinx_gallery.GalleryConfig` is recommended as it
      provides type hints, which can be helpful for IDEs and linters.

More details can be found in the :ref:`configuration` section.

Enhancements for customizing
----------------------------

Thumbnail Configuration
^^^^^^^^^^^^^^^^^^^^^^^

Added a new class :class:`~myst_sphinx_gallery.ThumbnailConfig` to configure
the thumbnail settings. The class supports custom thumbnail sizes, operations,
operation arguments, quality, and more.

.. code-block:: python
    :caption: conf.py
    :emphasize-lines: 1, 9

    from myst_sphinx_gallery import generate_gallery, GalleryConfig, ThumbnailConfig

    generate_gallery(
        GalleryConfig(
            examples_dirs="../../examples3",
            gallery_dirs="auto_examples3",
            root_dir=Path(__file__).parent,
            thumbnail_config=ThumbnailConfig(
                ref_size=(320, 320),
                operation="pad",
                operation_kwargs={"color": "orange"},
            ),
            ..., # other configurations
        )
    )

Customizing layout
^^^^^^^^^^^^^^^^^^

In this release, we added the ability to customize the layout of the gallery
using the :class:`~myst_sphinx_gallery.Grid` and
:class:`~myst_sphinx_gallery.GridItemCard` classes.

Following code is an example of customizing the layout of the gallery:

.. code-block:: python
    :caption: conf.py

    from myst_sphinx_gallery import generate_gallery, GalleryConfig, Grid, GridItemCard

    generate_gallery(
        GalleryConfig(
            examples_dirs="../../examples3",
            gallery_dirs="auto_examples3",
            root_dir=Path(__file__).parent,
            grid=Grid(
                grid_args=(1, 2, 2, 2),
                margin=3,
                padding=2,
            ),
            grid_item_card=GridItemCard(columns=5, margin=3, padding=3),
            ..., # other configurations
        )
    )

You can also using CSS to customize the layout of the gallery. More details
can be found in the :ref:`custom` section.