Merge pull request #5 from Fanchengyan/dev

update to v0.2.1

.pre-commit-config.yaml

@@ -8,7 +8,11 @@ repos:
  - id: trailing-whitespace
  args: ["--markdown-linebreak-ext=md"]
  - id: mixed-line-ending
-- repo: https://github.com/psf/black
- rev: 22.3.0
- hooks:
- - id: black
+- repo: https://github.com/astral-sh/ruff-pre-commit
+ # Ruff version.
+ rev: v0.6.1
+ hooks:
+ # Run the linter.
+ - id: ruff
+ # Run the formatter.
+ - id: ruff-format

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+ "python.testing.pytestArgs": [
+ "tests"
+ ],
+ "python.testing.unittestEnabled": false,
+ "python.testing.pytestEnabled": true
+}

docs/source/_static/css/gallery.css

@@ -17,4 +17,5 @@
 .myst-gallery-grid-item .sd-card-title .reference {
  color: var(--pst-color-warning);
  font-size: var(--pst-font-size-h5);
+ font-weight: lighter;
 }

docs/source/changelog/index.rst

@@ -0,0 +1,11 @@
+=============
+Release notes
+=============
+
+This is the list of changes to MyST Sphinx Gallery between each release. For full details, see the `commit logs <https://github.com/Fanchengyan/myst-sphinx-gallery/commits/main/>`_. For install and usage instructions, see :ref:`quick_start`.
+
+.. toctree::
+ :maxdepth: 2
+
+ v0.2.1
+ v0.2.0

docs/source/changelog/v0.2.0.rst

@@ -0,0 +1,105 @@
+==================================
+What’s new in 0.2.0 (Aug 17, 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_option=(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.

docs/source/changelog/v0.2.1.rst

@@ -0,0 +1,29 @@
+==================================
+What’s new in 0.2.1 (Aug 17, 2024)
+==================================
+
+Enhancements
+------------
+
+Thumbnails
+^^^^^^^^^^
+
+:class:`~myst_sphinx_gallery.ThumbnailConfig` now supports two new options:
+``quality_static`` and ``quality_animated``, to control the quality of those
+two types of thumbnails separately.
+
+
+Cross-referencing
+^^^^^^^^^^^^^^^^^
+
+- :class:`~myst_sphinx_gallery.GalleryConfig` now supports a new option:
+ ``target_prefix`` to customize the prefix of the target for the
+ cross-referencing.
+- ``GALLERY_HEADER.rst`` now will be added a target automatically based on the
+ folder name.
+
+Changes
+-------
+
+Code linter and formatter now change to `ruff <https://docs.astral.sh/ruff/>`_
+from `black <https://black.readthedocs.io/en/stable/>`_.

docs/source/conf.py

@@ -1,16 +1,7 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+# -- Gallery Configuration ---------------------------------------------------
 
-project = "MyST Sphinx Gallery"
-copyright = "2024, Fan Chengyan (Fancy)"
-author = "Fan Chengyan (Fancy)"
-
-# -- MyST Sphinx Gallery Configuration ---------------------------------------
+import os
+import sys
 from pathlib import Path
 
 from myst_sphinx_gallery import (
@@ -61,13 +52,25 @@
  ref_size=(320, 320),
  operation="pad",
  operation_kwargs={"color": "orange"},
- save_kwargs={"quality": 90},
+ quality_static=90,
  ),
+ target_prefix="myst_gallery_",
  grid=myst_gallery_grid,
  grid_item_card=myst_gallery_grid_item,
  )
 )
 
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "MyST Sphinx Gallery"
+copyright = "2024, Fan Chengyan (Fancy)"
+author = "Fan Chengyan (Fancy)"
 release = f"v{__version__}"
 
 # -- General configuration ---------------------------------------------------
@@ -163,8 +166,5 @@
 
 
 # -- myst_sphinx_gallery package ----------------------------------------------------------
-import os
-import sys
-
-# Location of Sphinx files
+# Location of MyST Sphinx Gallery files
 sys.path.insert(0, os.path.abspath("./../.."))

docs/source/index.rst

@@ -34,6 +34,7 @@ Highlight Features
  examples
  api/index
  contributing/index
+ changelog/index
 
 
 

docs/source/user_guide/cross_reference.rst

@@ -4,55 +4,79 @@
 Cross-reference to Examples in Gallery
 ======================================
 
-Targets of Example files
-------------------------
+When you generate the gallery, each example file will be automatically added
+a target for cross-referencing. This feature allows you to refer to those
+example files in the other documentation files.
 
-Each example file will be automatically added a target for cross-referencing. The target is generated by adding the prefix ``example_`` to the file name, while remove the file suffix and number prefix (if exists).
+Rule for generating targets
+---------------------------
 
+**For example files**:
 
-For example, the file ``examples/basic/01-basic-example1.ipynb`` will be added a target named ``example_basic-example1`` in the first line/(markdown cell) of the file. You can refer to this target in the documentation using the following syntax:
+- removing the number prefix ``dd-`` (if exists) and file suffix.
+- converring the letters in the file name to lowercase (target must be small letters).
+- adding the prefix to the file name. (default is ``example_``)
 
-in a ReStructuredText file (``*.rst``)
+.. note::
 
-.. code-block:: rst
+ The target is generated based on the file name, so you need to make sure the file name is unique.
 
- :ref:`example_basic-example1`
 
-in a Markdown/Notebook file ( ``*.md``/ ``*.ipynb`` ) with MyST syntax
+**For GALLERY_HEADER.rst file**:
 
-.. code-block:: markdown
+The rules are the same as the example files, except that the
+**target is generated based on the folder name**.
+
+.. versionchanged:: 0.2.1
+
+ Before version 0.2.1, you need to add the target manually in the
+ ``GALLERY_HEADER.rst`` file.
 
- [Basic Usages](#example_basic-example1)
 
-``GALLERY_HEADER.rst`` files
+
+Example of target generation
 ----------------------------
 
-**You need to manually add a target in the first line** of the ``GALLERY_HEADER.rst`` file to enable cross-referencing.
+For example, the file ``examples/basic/01-Basic-Example1.ipynb`` will be added
+a target named ``example_basic-example1`` in the first line/(markdown cell) of
+the file.
 
-For example, the file ``GALLERY_HEADER.rst`` contains the following content:
+You can refer to this target in the documentation using the following syntax:
+
+in a ReStructuredText file (``*.rst``)
 
 .. code-block:: rst
- :emphasize-lines: 1
 
- .. _example_basic_usages:
+ :ref:`example_basic-example1`
 
- ============
- Basic Usages
- ============
+in a Markdown/Notebook file ( ``*.md``/ ``*.ipynb`` ) with MyST syntax
 
- This section contains basic usages of the library. ...
+.. code-block:: markdown
 
+ [Basic Usages](#example_basic-example1)
 
-Then you can refer to this target in the documentation using the following syntax:
 
-in a ReStructuredText file (``*.rst``)
+Customizing the target prefix
+-----------------------------
 
-.. code-block:: rst
+.. versionadded:: 0.2.1
 
- :ref:`example_basic_usages`
+You can customize the target prefix by setting the ``target_prefix`` parameter in the :class:`~myst_sphinx_gallery.GalleryConfig` class in the ``conf.py`` file.
 
-in a Markdown/Notebook file (``*.md,`` ``*.ipynb``) with MyST syntax
+For example, you can change the target prefix to ``myst_gallery_`` by adding the following code in the ``conf.py`` file:
 
-.. code-block:: markdown
+.. code-block:: python
+ :caption: conf.py
+ :emphasize-lines: 8
+
+ from myst_sphinx_gallery import generate_gallery, GalleryConfig
 
- [Basic Usages](#example_basic_usages)
+ generate_gallery(
+ GalleryConfig(
+ examples_dirs="../../examples",
+ gallery_dirs="auto_examples",
+ root_dir=Path(__file__).parent,
+ target_prefix="myst_gallery_",
+ ...
+ )
+ )