Merge branch 'main' into grdcut-polygon

weiji14 · web-flow · commit 5078cb432fc8 · 2025-10-14T09:33:32.000+13:00
diff --git a/.github/workflows/benchmarks.yml b/.github/workflows/benchmarks.yml
@@ -48,7 +48,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           cache-environment: true
diff --git a/.github/workflows/cache_data.yaml b/.github/workflows/cache_data.yaml
@@ -46,7 +46,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           create-args: >-
diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml
@@ -53,7 +53,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
+        # os: [ubuntu-latest, macos-latest, windows-latest]
         # Is it a draft Pull Request (true or false)?
         isDraft:
           - ${{ github.event.pull_request.draft }}
@@ -83,7 +84,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           cache-environment: true
diff --git a/.github/workflows/ci_doctests.yaml b/.github/workflows/ci_doctests.yaml
@@ -45,7 +45,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           create-args: >-
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -51,6 +51,8 @@ jobs:
   test:
     name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
+    environment:
+      name: pr-tests
     permissions:
       id-token: write  # This is required for requesting OIDC token for codecov
     strategy:
@@ -116,7 +118,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           cache-environment: true
@@ -151,7 +153,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        uses: astral-sh/setup-uv@eb1897b8dc4b5d5bfe39a428a8f2304605e0983c # v7.0.0
         with:
           activate-environment: true
           python-version: ${{ matrix.python-version }}
diff --git a/.github/workflows/ci_tests_dev.yaml b/.github/workflows/ci_tests_dev.yaml
@@ -60,7 +60,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           cache-environment: true
diff --git a/.github/workflows/ci_tests_legacy.yaml b/.github/workflows/ci_tests_legacy.yaml
@@ -54,7 +54,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@b09ef9b599704322748535812ca03efb2625677b # v2.0.5
+        uses: mamba-org/setup-micromamba@add3a49764cedee8ee24e82dfde87f5bc2914462 # v2.0.7
         with:
           environment-name: pygmt
           create-args: >-
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,25 +1,24 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
-- repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v5.0.0
-  hooks:
-    - id: check-added-large-files
-    - id: check-yaml
-    - id: end-of-file-fixer
-    - id: trailing-whitespace
-- repo: https://github.com/Lucas-C/pre-commit-hooks
-  rev: v1.5.5
-  hooks:
-    - id: forbid-crlf
-    - id: remove-crlf
-    - id: chmod
-      args: ['644']
-- repo: https://github.com/woodruffw/zizmor-pre-commit
-  rev: v1.11.0
-  hooks:
-  - id: zizmor
-
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.5
+    hooks:
+      - id: forbid-crlf
+      - id: remove-crlf
+      - id: chmod
+        args: ["644"]
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.14.2
+    hooks:
+      - id: zizmor
 
 # https://pre-commit.ci/#configuration
 ci:
diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
@@ -8,7 +8,7 @@
 .. rubric:: Attributes
 
 {% for item in attributes %}
-.. autoproperty::
+.. autoattribute::
     {{ objname }}.{{ item }}
 {% endfor %}
 {% endif %}
diff --git a/doc/_templates/autosummary/params.rst b/doc/_templates/autosummary/params.rst
@@ -0,0 +1,14 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
+    :member-order: bysource
+
+.. minigallery:: {{ fullname }}
+    :add-heading:
+
+.. raw:: html
+
+     <div style='clear:both'></div>
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -210,6 +210,7 @@ Class-style Parameters
 
 .. autosummary::
     :toctree: generated
+    :template: autosummary/params.rst
 
     Box
     Pattern
diff --git a/doc/maintenance.md b/doc/maintenance.md
@@ -30,7 +30,7 @@ communication tools we use.
 ### As an Administrator
 
 - Add to the [pygmt-admin team](https://github.com/orgs/GenericMappingTools/teams/pygmt-admin) (gives 'admin' permission to the repository)
-- Add as an admin on [DAGsHub](https://www.dagshub.com/GenericMappingTools/pygmt)
+- Add as an admin on [DAGsHub](https://dagshub.com/GenericMappingTools/pygmt)
 - Add as a maintainer on [PyPI](https://pypi.org/project/pygmt/) and [Test PyPI](https://test.pypi.org/project/pygmt) [optional]
 
 **Note**: When a maintainer is no longer active (no activity in one year), we will mirror
diff --git a/pygmt/datasets/load_remote_dataset.py b/pygmt/datasets/load_remote_dataset.py
@@ -17,49 +17,41 @@
 class Resolution(NamedTuple):
     """
     Resolution code, the available grid registrations and whether it is tiled.
-
-    Attributes
-    ----------
-    code
-        The resolution code. E.g., "01d", "30m", "01s".
-    registrations
-        A list of the accepted registrations for a given resolution. Can be either
-        "pixel" or "gridline".
-    tiled
-        States if the grid is tiled, which requires an argument for ``region``.
     """
 
+    #: The resolution code. E.g., "01d", "30m", "01s".
     code: str
+
+    #: A list of the accepted registrations for a given resolution. Can be either
+    #: "pixel" or "gridline".
     registrations: Sequence[str] = ["gridline", "pixel"]
+
+    #: States if the grid is tiled, which requires an argument for ``region``.
     tiled: bool = False
 
 
 class GMTRemoteDataset(NamedTuple):
     """
     Standard information about a dataset and grid metadata.
-
-    Attributes
-    ----------
-    description
-        The name assigned as an attribute to the DataArray.
-    kind
-        The kind of the dataset source. Valid values are ``"grid"`` and ``"image"``.
-    units
-        The units of the values in the DataArray.
-    resolutions
-        Dictionary of available resolution as keys and Resolution objects as values.
-    extra_attributes
-        A dictionary of extra or unique attributes of the dataset.
-    crs
-        The coordinate reference system of the raster image. Need to be set for images,
-        and should be ``None`` for grids.
     """
 
+    #: The name assigned as an attribute to the DataArray.
     description: str
+
+    #: The kind of the dataset source. Valid values are ``"grid"`` and ``"image"``.
     kind: Literal["grid", "image"]
+
+    #: The units of the values in the DataArray.
     units: str | None
+
+    #: Dictionary of available resolution as keys and Resolution objects as values.
     resolutions: Mapping[str, Resolution]
+
+    #: A dictionary of extra or unique attributes of the dataset.
     extra_attributes: Mapping[str, Any]
+
+    #: The coordinate reference system of the raster image. Need to be set for images,
+    #: and should be ``None`` for grids.
     crs: str | None = None
 
 
diff --git a/pygmt/datasets/samples.py b/pygmt/datasets/samples.py
@@ -209,16 +209,11 @@ def _load_earth_relief_holes() -> xr.DataArray:
 class GMTSampleData(NamedTuple):
     """
     Information of a sample dataset.
-
-    Attributes
-    ----------
-    func : callable
-        The function that loads the sample dataset.
-    description : str
-        The description of the sample dataset.
     """
 
+    #: The function that loads the sample dataset.
     func: Callable
+    #: The description of the sample dataset.
     description: str
 
 
diff --git a/pygmt/datatypes/image.py b/pygmt/datatypes/image.py
@@ -7,8 +7,14 @@
 
 import numpy as np
 import xarray as xr
+from packaging.version import Version
 from pygmt.datatypes.header import _GMT_GRID_HEADER
 
+# TODO(xarray>=2025.10.1): Remove the __doctest_skip__ on _GMT_IMAGE.to_xarray
+__doctest_skip__ = (
+    ["_GMT_IMAGE.to_xarray"] if Version(xr.__version__) < Version("2025.10.1") else []
+)
+
 
 class _GMT_IMAGE(ctp.Structure):  # noqa: N801
     """
@@ -115,8 +121,8 @@ def to_xarray(self) -> xr.DataArray:
         ...         image = lib.read_virtualfile(voutimg, kind="image")
         ...         # Convert to xarray.DataArray and use it later
         ...         da = image.contents.to_xarray()
-        >>> da  # doctest: +NORMALIZE_WHITESPACE, +ELLIPSIS
-        <xarray.DataArray 'z' (band: 3, y: 180, x: 360)>...
+        >>> da  # doctest: +NORMALIZE_WHITESPACE
+        <xarray.DataArray 'z' (band: 3, y: 180, x: 360)> Size: 194kB
         array([[[ 10,  10,  10, ...,  10,  10,  10],
                 [ 10,  10,  10, ...,  10,  10,  10],
                 [ 10,  10,  10, ...,  10,  10,  10],
@@ -141,26 +147,26 @@ def to_xarray(self) -> xr.DataArray:
                 [185, 187, 187, ..., 187, 186, 185],
                 [189, 191, 191, ..., 191, 191, 189]]], dtype=uint8)
         Coordinates:
-          * y        (y) float64... 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
-          * x        (x) float64... -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
-          * band     (band) uint8... 1 2 3
+          * band     (band) uint8 3B 1 2 3
+          * y        (y) float64 1kB 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
+          * x        (x) float64 3kB -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
         Attributes:
-            long_name:     z
+            long_name:  z
 
-        >>> da.coords["x"]  # doctest: +NORMALIZE_WHITESPACE, +ELLIPSIS
-        <xarray.DataArray 'x' (x: 360)>...
+        >>> da.coords["x"]  # doctest: +NORMALIZE_WHITESPACE
+        <xarray.DataArray 'x' (x: 360)> Size: 3kB
         array([-179.5, -178.5, -177.5, ...,  177.5,  178.5,  179.5])
         Coordinates:
-          * x        (x) float64... -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
+          * x        (x) float64 3kB -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
         Attributes:
             long_name:     x
             axis:          X
             actual_range:  [-180.  180.]
-        >>> da.coords["y"]  # doctest: +NORMALIZE_WHITESPACE, +ELLIPSIS
-        <xarray.DataArray 'y' (y: 180)>...
+        >>> da.coords["y"]  # doctest: +NORMALIZE_WHITESPACE
+        <xarray.DataArray 'y' (y: 180)> Size: 1kB
         array([ 89.5,  88.5,  87.5,  86.5,  ...,   -87.5, -88.5, -89.5])
         Coordinates:
-          * y        (y) float64... 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
+          * y        (y) float64 1kB 89.5 88.5 87.5 86.5 ... -86.5 -87.5 -88.5 -89.5
         Attributes:
             long_name:     y
             axis:          Y
diff --git a/pygmt/params/box.py b/pygmt/params/box.py
@@ -18,33 +18,6 @@ class Box(BaseParam):
     """
     Class for specifying the box around GMT embellishments.
 
-    Parameters
-    ----------
-    clearance
-        Set clearances between the embellishment and the box border. It can be either a
-        scalar value or a sequence of two/four values.
-
-        - a scalar value means a uniform clearance in all four directions.
-        - a sequence of two values means separate clearances in x- and y-directions.
-        - a sequence of four values means separate clearances for left/right/bottom/top.
-    fill
-        Fill for the box [Default is no fill].
-    inner_gap
-        Gap between the outer and inner borders [Default is ``"2p"``].
-    inner_pen
-        Pen attributes for the inner border [Default to :gmt-term:`MAP_DEFAULT_PEN`].
-    pen
-        Pen attributes for the box outline.
-    radius
-        Draw a rounded rectangular border instead of sharp. Passing a value with unit
-        to control the corner radius [Default is ``"6p"``].
-    shade_offset
-        Place an offset background shaded region behind the box. A sequence of two
-        values (dx, dy) indicates the shift relative to the foreground frame [Default is
-        ``("4p", "-4p")``].
-    shade_fill
-        Fill for the shaded region [Default is ``"gray50"``].
-
     Examples
     --------
     >>> import pygmt
@@ -54,13 +27,36 @@ class Box(BaseParam):
     >>> fig.show()
     """
 
+    #: Set clearances between the embellishment and the box border. It can be either a
+    #: scalar value or a sequence of two/four values.
+    #:
+    #: - a scalar value means a uniform clearance in all four directions.
+    #: - a sequence of two values means separate clearances in x- and y-directions.
+    #: - a sequence of four values means separate clearances for left/right/bottom/top.
     clearance: float | str | Sequence[float | str] | None = None
+
+    #: Fill for the box [Default is no fill].
     fill: str | None = None
+
+    #: Gap between the outer and inner borders [Default is ``"2p"``].
     inner_gap: float | str | None = None
+
+    #: Pen attributes for the inner border [Default to :gmt-term:`MAP_DEFAULT_PEN`].
     inner_pen: str | None = None
+
+    #: Pen attributes for the box outline.
     pen: str | None = None
+
+    #: Draw a rounded rectangular border instead of sharp. Passing a value with unit to
+    #: control the corner radius [Default is ``"6p"``].
     radius: str | bool = False
+
+    #: Place an offset background shaded region behind the box. A sequence of two values
+    #: (dx, dy) indicates the shift relative to the foreground frame [Default is
+    #: ``("4p", "-4p")``].
     shade_offset: Sequence[float | str] | None = None
+
+    #: Fill for the shaded region [Default is ``"gray50"``].
     shade_fill: str | None = None
 
     def _validate(self):
diff --git a/pygmt/params/pattern.py b/pygmt/params/pattern.py
diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
diff --git a/pygmt/xarray/backend.py b/pygmt/xarray/backend.py
