Merge branch 'main' into python-3.13

Author: weiji14

.github/workflows/benchmarks.yml

@@ -25,7 +25,7 @@ concurrency:
 
 jobs:
   benchmarks:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     if: github.repository == 'GenericMappingTools/pygmt' && (github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'run/benchmark'))
     defaults:
       run:
@@ -34,7 +34,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0
@@ -88,7 +88,7 @@ jobs:
 
       # Run the benchmark tests
       - name: Run benchmarks
-        uses: CodSpeedHQ/action@v3.0.1
+        uses: CodSpeedHQ/action@v3.1.0
         with:
           # 'bash -el -c' is needed to use the custom shell.
           # See https://github.com/CodSpeedHQ/action/issues/65.

.github/workflows/cache_data.yaml

@@ -36,7 +36,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0
@@ -76,7 +76,7 @@ jobs:
 
       # Upload the downloaded files as artifacts to GitHub
       - name: Upload artifacts to GitHub
-        uses: actions/[email protected].0
+        uses: actions/[email protected].3
         with:
           name: gmt-cache
           include-hidden-files: true

.github/workflows/check-links.yml

@@ -23,12 +23,12 @@ jobs:
 
     steps:
     - name: Checkout the repository
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
       with:
         path: repository
 
     - name: Checkout the documentation
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
       with:
         ref: gh-pages
         path: documentation

.github/workflows/ci_docs.yml

@@ -69,7 +69,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0
@@ -104,6 +104,7 @@ jobs:
             contextily
             geopandas<1.0
             ipython
+            pyarrow
             rioxarray
             make
             pip
@@ -115,7 +116,7 @@ jobs:
             sphinx-copybutton
             sphinx-design
             sphinx-gallery
-            sphinx_rtd_theme
+            sphinx_rtd_theme<3.0
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
@@ -139,7 +140,7 @@ jobs:
         run: make -C doc clean all
 
       - name: Checkout the gh-pages branch
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           ref: gh-pages
           # Checkout to this folder instead of the current one

.github/workflows/ci_doctests.yaml

@@ -35,7 +35,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0

.github/workflows/ci_tests.yaml

@@ -85,9 +85,9 @@ jobs:
           - os: 'ubuntu-latest'
             python-version: '3.11'  # Can't be 3.10 or 3.13.
             numpy-version: '1.24'
-            pandas-version: ''
+            pandas-version: '=2.1'
             xarray-version: ''
-            optional-packages: ' geopandas<1'
+            optional-packages: ' geopandas<1 pyarrow'
 
     timeout-minutes: 30
     defaults:
@@ -103,7 +103,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0
@@ -171,7 +171,7 @@ jobs:
 
       # Upload diff images on test failure
       - name: Upload diff images if any test fails
-        uses: actions/[email protected].0
+        uses: actions/[email protected].3
         if: failure()
         with:
           name: artifact-${{ runner.os }}-${{ matrix.python-version }}

.github/workflows/ci_tests_dev.yaml

@@ -46,7 +46,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0
@@ -87,9 +87,17 @@ jobs:
             pcre
             zlib
 
+      # Install the GSHHG and DCW datasets on Linux/macOS to avoid corrupted files
+      # during GMT auto-downloading. Currently, we can't install them on Windows CI,
+      # because the Windows CI fails to compile "gshhg_version.c" due to unknown reasons
+      # (likely missing DLLs).
+      - name: Install GMT GSHHG and DCW datasets (Linux/macOS)
+        run: micromamba install dcw-gmt gshhg-gmt
+        if: runner.os != 'Windows'
+
       # Checkout current GMT repository
       - name: Checkout the GMT source from ${{ matrix.gmt_git_ref }} branch
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           repository: 'GenericMappingTools/gmt'
           ref: ${{ matrix.gmt_git_ref }}
@@ -180,7 +188,7 @@ jobs:
 
       # Upload diff images on test failure
       - name: Upload diff images if any test fails
-        uses: actions/[email protected].0
+        uses: actions/[email protected].3
         if: ${{ failure() }}
         with:
           name: artifact-GMT-${{ matrix.gmt_git_ref }}-${{ runner.os }}

.github/workflows/ci_tests_legacy.yaml

@@ -44,7 +44,7 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
         with:
           # fetch all history so that setuptools-scm works
           fetch-depth: 0

.github/workflows/dvc-diff.yml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
       with:
         # fetch all history so that dvc diff works
         fetch-depth: 0

.github/workflows/format-command.yml

@@ -18,14 +18,14 @@ jobs:
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
 
       # Checkout the pull request branch
-      - uses: actions/[email protected].1
+      - uses: actions/[email protected].2
         with:
           token: ${{ steps.generate-token.outputs.token }}
           repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
           ref: ${{ github.event.client_payload.pull_request.head.ref }}
 
       # Setup Python environment
-      - uses: actions/setup-python@v5.2.0
+      - uses: actions/setup-python@v5.3.0
         with:
           python-version: '3.13'
 

.github/workflows/publish-to-pypi.yml

@@ -45,13 +45,13 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
       with:
         # fetch all history so that setuptools-scm works
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@v5.2.0
+      uses: actions/setup-python@v5.3.0
       with:
         python-version: '3.13'
 
@@ -75,10 +75,10 @@ jobs:
         ls -lh dist/
 
     - name: Publish to Test PyPI
-      uses: pypa/gh-action-pypi-publish@v1.10.3
+      uses: pypa/gh-action-pypi-publish@v1.12.0
       with:
         repository-url: https://test.pypi.org/legacy/
 
     - name: Publish to PyPI
       if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@v1.10.3
+      uses: pypa/gh-action-pypi-publish@v1.12.0

.github/workflows/release-baseline-images.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/[email protected].1
+      uses: actions/[email protected].2
 
     - name: Setup data version control (DVC)
       uses: iterative/[email protected]

.github/workflows/style_checks.yaml

@@ -24,11 +24,11 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
 
       # Setup Python
       - name: Set up Python
-        uses: actions/setup-python@v5.2.0
+        uses: actions/setup-python@v5.3.0
         with:
           python-version: '3.13'
 

.github/workflows/type_checks.yml

@@ -33,11 +33,11 @@ jobs:
     steps:
       # Checkout current git repository
       - name: Checkout
-        uses: actions/[email protected].1
+        uses: actions/[email protected].2
 
       # Setup Python
       - name: Set up Python
-        uses: actions/setup-python@v5.2.0
+        uses: actions/setup-python@v5.3.0
         with:
           python-version: '3.13'
 
@@ -50,8 +50,8 @@ jobs:
           # 4. other packages that are used somewhere in PyGMT
           python -m pip install \
             numpy pandas xarray netcdf4 packaging \
-            contextily geopandas ipython rioxarray \
-            mypy pandas-stubs \
+            contextily geopandas ipython pyarrow rioxarray \
+            mypy pandas-stubs pyarrow-stubs \
             matplotlib pytest
           python -m pip list
 

.gitignore

@@ -27,14 +27,14 @@ tmp-test-dir-with-unique-name/
 # Sphinx documentation
 doc/api/generated/
 doc/_build/
+doc/intro/
+doc/tutorials/
 doc/gallery/
 doc/projections/
-doc/tutorials/
-doc/get_started/
 # doc/sg_execution_time.rst is auto-generated by Sphinx-Gallery
 doc/sg_execution_times.rst
 
-# Jupyter Notebook
+# Jupyter notebook
 .ipynb_checkpoints/
 
 # Visual Studio Code

README.md

@@ -4,19 +4,19 @@
 
 [Documentation (development version)](https://www.pygmt.org/dev) | [Contact](https://forum.generic-mapping-tools.org) | [TryOnline](https://github.com/GenericMappingTools/try-gmt)
 
-[![Latest version on PyPI](https://img.shields.io/pypi/v/pygmt.svg?style=flat-square)](https://pypi.python.org/pypi/pygmt)
-[![Latest version on conda-forge](https://img.shields.io/conda/v/conda-forge/pygmt?style=flat-square)](https://anaconda.org/conda-forge/pygmt)
-[![GitHub Actions Tests status](https://github.com/GenericMappingTools/pygmt/workflows/Tests/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml)
-[![GitHub Actions GMT Dev Tests status](https://github.com/GenericMappingTools/pygmt/workflows/GMT%20Dev%20Tests/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-[![Test coverage status](https://codecov.io/gh/GenericMappingTools/pygmt/branch/main/graph/badge.svg?token=78Fu4EWstx)](https://app.codecov.io/gh/GenericMappingTools/pygmt)
-[![CodSpeed Performance Benchmarks](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/GenericMappingTools/pygmt)
-[![Compatible Python versions.](https://img.shields.io/pypi/pyversions/pygmt.svg?style=flat-square)](https://pypi.python.org/pypi/pygmt)
-[![Discourse forum](https://img.shields.io/discourse/status?label=forum&server=https%3A%2F%2Fforum.generic-mapping-tools.org%2F&style=flat-square)](https://forum.generic-mapping-tools.org)
+[![Latest version on PyPI](https://img.shields.io/pypi/v/pygmt)](https://pypi.org/project/pygmt)
+[![Latest version on conda-forge](https://img.shields.io/conda/v/conda-forge/pygmt)](https://anaconda.org/conda-forge/pygmt)
+[![GitHub license](https://img.shields.io/github/license/GenericMappingTools/pygmt)](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt)
+[![Compatible Python versions](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FGenericMappingTools%2Fpygmt%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://www.pygmt.org/dev/minversions.html)
 [![Digital Object Identifier for the Zenodo archive](https://zenodo.org/badge/DOI/10.5281/3781524.svg)](https://doi.org/10.5281/zenodo.3781524)
+[![Discourse forum](https://img.shields.io/discourse/status?label=forum&server=https%3A%2F%2Fforum.generic-mapping-tools.org)](https://forum.generic-mapping-tools.org)
 [![PyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/43)
-[![GitHub license](https://img.shields.io/github/license/GenericMappingTools/pygmt?style=flat-square)](https://github.com/GenericMappingTools/pygmt/blob/main/LICENSE.txt)
 [![Contributor Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](https://github.com/GenericMappingTools/.github/blob/main/CODE_OF_CONDUCT.md)
+[![GitHub Actions Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests.yaml)
+[![GitHub Actions GMT Dev Tests status](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml/badge.svg)](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml)
+[![Test coverage status](https://codecov.io/gh/GenericMappingTools/pygmt/graph/badge.svg?token=78Fu4EWstx)](https://app.codecov.io/gh/GenericMappingTools/pygmt)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![CodSpeed Performance Benchmarks](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/GenericMappingTools/pygmt)
 
 <!-- doc-index-start-after -->
 
@@ -191,7 +191,7 @@ Other official wrappers for GMT:
 ## Minimum supported versions
 
 PyGMT has adopted [SPEC 0](https://scientific-python.org/specs/spec-0000/) alongside the
-rest of the Scientific Python ecosystem, and therefore:
+rest of the scientific Python ecosystem, and therefore:
 
 - Support for Python versions be dropped 3 years after their initial release.
 - Support for core package dependencies (NumPy, pandas, Xarray) be dropped 2 years after

ci/requirements/docs.yml

@@ -17,6 +17,7 @@ dependencies:
     - contextily
     - geopandas<1.0
     - ipython
+    - pyarrow
     - rioxarray
     # Development dependencies (general)
     - make
@@ -30,4 +31,4 @@ dependencies:
     - sphinx-copybutton
     - sphinx-design
     - sphinx-gallery
-    - sphinx_rtd_theme
+    - sphinx_rtd_theme<3.0

doc/Makefile

@@ -55,7 +55,7 @@ server:
 clean:
 	rm -rf $(BUILDDIR)
 	rm -rf api/generated
-	rm -rf gallery
+	rm -rf intro
 	rm -rf tutorials
-	rm -rf get_started
+	rm -rf gallery
 	rm -rf projections

doc/changes.md

@@ -361,7 +361,7 @@
 * Exclude DVC files from source/binary distributions ([#2634](https://github.com/GenericMappingTools/pygmt/pull/2634))
 * CI: Use mamba-org/provision-with-micromamba to setup micromamba ([#2435](https://github.com/GenericMappingTools/pygmt/pull/2435))
 * CI: Migrate provision-with-micromamba to setup-micromamba ([#2536](https://github.com/GenericMappingTools/pygmt/pull/2536))
-* CI: Run dev tests on Scientific Python nightly wheels ([#2612](https://github.com/GenericMappingTools/pygmt/pull/2612))
+* CI: Run dev tests on scientific Python nightly wheels ([#2612](https://github.com/GenericMappingTools/pygmt/pull/2612))
 * CI: Remove the deprecated cml-publish command from the dvc-diff workflow ([#2559](https://github.com/GenericMappingTools/pygmt/pull/2559))
 * CI: Fix and simplify the dvc-diff workflow ([#2549](https://github.com/GenericMappingTools/pygmt/pull/2549))
 * CI: Add the "Doctests" workflow to run doctests weekly ([#2456](https://github.com/GenericMappingTools/pygmt/pull/2456))