Merge branch 'main' into enums/grid-reg-type

.github/ISSUE_TEMPLATE/4-release_checklist.md

@@ -19,17 +19,15 @@ assignees: ''
 
 **Before release**:
 
-- [ ] Check [SPEC 0](https://scientific-python.org/specs/spec-0000/) to see if we need to bump the minimum supported versions of GMT, Python and
-      core package dependencies (NumPy, pandas, Xarray)
+- [ ] Check [SPEC 0](https://scientific-python.org/specs/spec-0000/) to see if we need to bump the minimum supported versions of GMT, Python and core package dependencies (NumPy, pandas, Xarray)
 - [ ] Review the ["PyGMT Team" page](https://www.pygmt.org/dev/team.html)
+- [ ] README looks good on TestPyPI. Visit [TestPyPI](https://test.pypi.org/project/pygmt/#history), click the latest pre-release, and check the homepage.
 - [ ] Check to ensure that:
   - [ ] Deprecated workarounds/codes/tests are removed. Run `grep "# TODO" **/*.py` to find all potential TODOs.
   - [ ] All tests pass in the ["GMT Legacy Tests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_legacy.yaml)
   - [ ] All tests pass in the ["GMT Dev Tests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml)
   - [ ] All tests pass in the ["Doctests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_doctests.yaml)
-- [ ] Update warnings in `pygmt/_show_versions.py` as well as notes in
-      [Not working transparency](https://www.pygmt.org/dev/install.html#not-working-transparency)
-      regarding GMT-Ghostscript incompatibility
+- [ ] Update warnings in `pygmt/_show_versions.py` as well as notes in [Not working transparency](https://www.pygmt.org/dev/install.html#not-working-transparency) regarding GMT-Ghostscript incompatibility
 - [ ] Reserve a DOI on [Zenodo](https://zenodo.org) by clicking on "New Version"
 - [ ] Finish up the "Changelog entry for v0.x.x" Pull Request (Use the previous changelog PR as a reference)
 - [ ] Run `make codespell` to check common misspellings. If there are any, either fix them or add them to `ignore-words-list` in `pyproject.toml`
@@ -41,18 +39,16 @@ assignees: ''
   - [ ] Edit the draft release notes with the finalized changelog
   - [ ] Set the tag version and release title to vX.Y.Z
   - [ ] Make a release by clicking the 'Publish Release' button, this will automatically create a tag too
-- [ ] Download pygmt-X.Y.Z.zip (rename to pygmt-vX.Y.Z.zip) and baseline-images.zip from
-      the release page, and upload the two zip files to https://zenodo.org/deposit,
-      ensure that they are filed under the correct reserved DOI
+- [ ] Download pygmt-X.Y.Z.zip (rename to pygmt-vX.Y.Z.zip) and baseline-images.zip from the release page, and upload the two zip files to https://zenodo.org/deposit, ensure that they are filed under the correct reserved DOI
 
 **After release**:
 
-- [ ] Update conda-forge [pygmt-feedstock](https://github.com/conda-forge/pygmt-feedstock)
-      [Done automatically by conda-forge's bot. Remember to pin Python and SPEC0 versions]
+- [ ] Update conda-forge [pygmt-feedstock](https://github.com/conda-forge/pygmt-feedstock) [Done automatically by conda-forge's bot. Remember to pin GMT, Python and SPEC0 versions]
 - [ ] Bump PyGMT version on https://github.com/GenericMappingTools/try-gmt (after conda-forge update)
 - [ ] Announce the release on:
   - [ ] GMT [forum](https://forum.generic-mapping-tools.org/c/news/) (do this announcement first! Requires moderator status)
-  - [ ] [ResearchGate](https://www.researchgate.net) (after forum announcement, add new version as research item via the **code** category, be sure to include the corresponding new Zenodo DOI)
+  - [ ] [ResearchGate](https://www.researchgate.net) (after forum announcement; download the ZIP file of the new release from the release page and add it as research item via the **code** category, be sure to include the corresponding new Zenodo DOI)
+- [ ] Update release checklist template with any additional bullet points that may have arisen during the release
 
 ---
 

.github/workflows/check-links.yml

@@ -35,7 +35,7 @@ jobs:
 
     - name: Link Checker
       id: lychee
-      uses: lycheeverse/lychee-action@v2.1.0
+      uses: lycheeverse/lychee-action@v2.2.0
       with:
         fail: false  # Don't fail action on broken links
         output: /tmp/lychee-out.md

.github/workflows/ci_docs.yml

@@ -163,9 +163,14 @@ jobs:
           # to get the right commit hash.
           message="Deploy $version from $(git rev-parse --short HEAD)"
           cd deploy
-          # Need to have this file so that GitHub doesn't try to run Jekyll
+          # Create some files in the root directory.
+          # .nojekyll: Need to have this file so that GitHub doesn't try to run Jekyll
           touch .nojekyll
-          # Delete all the files and replace with our new  set
+          # CNAME: Set the custom domain name
+          echo "www.pygmt.org" > CNAME
+          # index.html: Redirect to the latest version
+          echo '<meta http-equiv="Refresh" content="0;url=latest/"/>' > index.html
+          # Delete all the files and replace with our new set
           echo -e "\nRemoving old files from previous builds of ${version}:"
           rm -rvf ${version}
           echo -e "\nCopying HTML files to ${version}:"

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

@@ -35,20 +35,17 @@ on:
   #    - main
 
 jobs:
-  publish-pypi:
-    name: Publish to PyPI
+  build:
+    name: Build distribution 📦
     runs-on: ubuntu-latest
-    permissions:
-      # This permission is mandatory for OIDC publishing
-      id-token: write
-    if: github.repository == 'GenericMappingTools/pygmt'
 
     steps:
     - name: Checkout
       uses: actions/[email protected]
       with:
         # fetch all history so that setuptools-scm works
         fetch-depth: 0
+        persist-credentials: false
 
     - name: Set up Python
       uses: actions/[email protected]
@@ -74,11 +71,54 @@ jobs:
         echo "Generated files:"
         ls -lh dist/
 
-    - name: Publish to Test PyPI
+    - name: Store the distribution packages
+      uses: actions/[email protected]
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-testpypi:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    if: github.repository == 'GenericMappingTools/pygmt'
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/pygmt
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted OIDC publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/[email protected]
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Publish distribution 📦 to TestPyPI
       uses: pypa/[email protected]
       with:
         repository-url: https://test.pypi.org/legacy/
 
-    - name: Publish to PyPI
-      if: startsWith(github.ref, 'refs/tags')
+  publish-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    if: github.repository == 'GenericMappingTools/pygmt' && startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pygmt/
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted OIDC publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/[email protected]
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Publish distribution 📦 to PyPI
       uses: pypa/[email protected]

doc/Makefile

@@ -1,14 +1,12 @@
 # Makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto
-SPHINXBUILD   = sphinx-build
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
 SPHINXAUTOGEN = sphinx-autogen
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Internal variables.
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees  $(SPHINXOPTS) .
-
 .PHONY: help all api html server clean
 
 help:
@@ -28,20 +26,20 @@ api:
 	@echo
 	$(SPHINXAUTOGEN) -i -t _templates -o api/generated api/*.rst
 
-html: api
+html latex: api
 	@echo
-	@echo "Building HTML files."
+	@echo "Building "$@" files."
 	@echo
 	# Set PYGMT_USE_EXTERNAL_DISPLAY to "false" to disable external display
-	PYGMT_USE_EXTERNAL_DISPLAY="false" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	PYGMT_USE_EXTERNAL_DISPLAY="false" $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The files are in $(BUILDDIR)/$@."
 
 html-noplot: api
 	@echo
 	@echo "Building HTML files without example plots."
 	@echo
-	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -D plot_gallery=0
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 

doc/changes.md

@@ -102,6 +102,8 @@
 * [Will Schlitzer](https://github.com/willschlitzer)
 * [Jiayuan Yao](https://github.com/core-man)
 
+---
+
 ## Release v0.13.0 (2024/09/05)
 
 [![Digital Object Identifier for PyGMT v0.13.0](https://zenodo.org/badge/DOI/10.5281/zenodo.13679420.svg)](https://doi.org/10.5281/zenodo.13679420)
@@ -280,6 +282,8 @@
 * [Michael Grund](https://github.com/michaelgrund)
 * [Wei Ji Leong](https://github.com/weiji14)
 
+---
+
 ## Release v0.11.0 (2024/02/01)
 
 [![Digital Object Identifier for PyGMT v0.11.0](https://zenodo.org/badge/DOI/10.5281/zenodo.10578540.svg)](https://doi.org/10.5281/zenodo.10578540)

doc/conf.py

@@ -210,12 +210,10 @@
 repository = "GenericMappingTools/pygmt"
 repository_url = "https://github.com/GenericMappingTools/pygmt"
 if __commit__:
-    commit_link = (
-        f'<a href="{repository_url}/commit/{ __commit__ }">{ __commit__[:8] }</a>'
-    )
+    commit_link = f'<a href="{repository_url}/commit/{__commit__}">{__commit__[:8]}</a>'
 else:
     commit_link = (
-        f'<a href="{repository_url}/releases/tag/{ __version__ }">{ __version__ }</a>'
+        f'<a href="{repository_url}/releases/tag/{__version__}">{__version__}</a>'
     )
 html_context = {
     "menu_links": [

doc/techref/patterns.md

@@ -11,7 +11,7 @@ image raster file. The former will result in one of the 90 predefined 64x64 bit-
 provided by GMT (see the figure below). The latter allows the user to create customized,
 repeating images using image raster files.
 
-By specifying upper case **P** instead of **p** the image will be bit-reversed, i.e.,
+By specifying uppercase **P** instead of **p** the image will be bit-reversed, i.e.,
 white and black areas will be interchanged (only applies to 1-bit images or predefined
 bit-image patterns). For these patterns and other 1-bit images one may specify
 alternative **b**ackground and **f**oreground colors (by appending **+b**_color_ and/or

environment.yml

@@ -27,7 +27,7 @@ dependencies:
     # Dev dependencies (style checks)
     - codespell
     - pre-commit
-    - ruff>=0.8.2
+    - ruff>=0.9.0
     # Dev dependencies (unit testing)
     - matplotlib-base
     - pytest>=6.0

examples/gallery/basemaps/double_y_axes.py

@@ -5,7 +5,7 @@
 The ``frame`` parameter of the plotting methods of the :class:`pygmt.Figure`
 class can control which axes should be plotted and optionally show annotations,
 tick marks, and gridlines. By default, all 4 axes are plotted, along with
-annotations and tick marks (denoted **W**, **S**, **E**, **N**). Lower case
+annotations and tick marks (denoted **W**, **S**, **E**, **N**). Lowercase
 versions (**w**, **s**, **e**, **n**) can be used to denote to only plot the
 axes with tick marks. We can also only plot the axes without annotations and
 tick marks using **l** (left axis), **r** (right axis), **t** (top axis),

examples/gallery/embellishments/scalebar.py

@@ -12,8 +12,9 @@
    - **g**: Give map coordinates as *longitude*\/\ *latitude*.
    - **j**\|\ **J**: Specify a two-character (order independent) code.
      Choose from vertical **T**\(op), **M**\(iddle), or **B**\(ottom) and
-     horizontal **L**\(eft), **C**\(entre), or **R**\(ight). Lower / upper
-     case **j** / **J** mean inside / outside of the map bounding box.
+     horizontal **L**\(eft), **C**\(entre), or **R**\(ight). Lower /
+     uppercase **j** / **J** mean inside / outside of the map bounding
+     box.
    - **n**: Give normalized bounding box coordinates as *nx*\/\ *ny*.
    - **x**: Give plot coordinates as *x*\/\ *y*.
 

examples/gallery/images/cross_section.py

@@ -37,7 +37,7 @@
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lower-case "j") in the Bottom Right (BR)
+    # Place the colorbar inside the plot (lowercase "j") in the Bottom Right (BR)
     # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x or y
     # directions, respectively; move the x label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",

examples/gallery/images/rgb_image.py

@@ -28,7 +28,7 @@
     # Subset to area of Lāhainā in EPSG:32604 coordinates
     image = img.rio.clip_box(minx=738000, maxx=755000, miny=2300000, maxy=2318000)
     image = image.load()  # Force loading the DataArray into memory
-image  # noqa: B018
+image
 
 # %%
 # Plot the RGB imagery:

examples/gallery/lines/decorated_lines.py

@@ -51,7 +51,7 @@
     "~d1c:+sd0.5c+gtan+p1p,black+n-0.2c/0.1c",
     # Give the number of equally spaced symbols by using "n" instead of "d"
     "~n6:+sn0.5c+gtan+p1p,black",
-    # Use upper-case "N" to have symbols at the start and end of the line
+    # Use uppercase "N" to have symbols at the start and end of the line
     "~N6:+sh0.5c+gtan+p1p,black",
     # Suppress the main decorated line by appending "+i"
     "~d1c:+sg0.5c+gtan+p1p,black+i",

examples/gallery/lines/linestrings.py

@@ -25,7 +25,7 @@
 
 # Convert object to EPSG 4326 coordinate system
 gdf = gdf.to_crs("EPSG:4326")
-print(gdf.head())
+gdf.head()
 
 # %%
 fig = pygmt.Figure()

examples/gallery/lines/quoted_lines.py

@@ -33,7 +33,7 @@
     "qd1c:+ltext+i",
     # Give the number of equally spaced labels by using "n" instead of "d"
     "qn5:+ltext",
-    # Use upper-case "N" to have labels at the start and end of the line
+    # Use uppercase "N" to have labels at the start and end of the line
     "qN5:+ltext",
     # To only plot a label at the start of the line use "N-1"
     "qN-1:+ltext",

examples/gallery/maps/choropleth_map.py

@@ -6,7 +6,7 @@
 polygons which are stored in a :class:`geopandas.GeoDataFrame` object. Use
 :func:`geopandas.read_file` to load data from any supported OGR format such as a
 shapefile (.shp), GeoJSON (.geojson), geopackage (.gpkg), etc. You can also use a full
-URL pointing to your desired data source. Then, pass the class:`geopandas.GeoDataFrame`
+URL pointing to your desired data source. Then, pass the :class:`geopandas.GeoDataFrame`
 as an argument to the ``data`` parameter of :meth:`pygmt.Figure.plot`, and style the
 geometry using the ``pen`` parameter. To fill the polygons based on a corresponding
 column you need to set ``fill="+z"`` as well as select the appropriate column using the
@@ -20,7 +20,7 @@
 
 # Read the example dataset provided by geodatasets.
 gdf = gpd.read_file(geodatasets.get_path("geoda airbnb"))
-print(gdf)
+print(gdf.head())
 
 # %%
 fig = pygmt.Figure()

examples/gallery/symbols/multi_parameter_symbols.py

@@ -33,7 +33,7 @@
 #   directions given in degrees counter-clockwise from horizontal. Append **+i** and the
 #   desired value to apply an inner diameter.
 #
-# Upper-case versions **E**, **J**, and **W** are similar to **e**, **j**, and **w**
+# Uppercase versions **E**, **J**, and **W** are similar to **e**, **j**, and **w**
 # but expect geographic azimuths and distances.
 
 fig = pygmt.Figure()

examples/projections/cyl/cyl_oblique_mercator.py

@@ -9,7 +9,7 @@
 
 The projection is set with **o** or **O**. There are three different specification
 ways (**a**\|\ **A**, **b**\|\ **B**, **c**\|\ **C**) available. For all three
-definitions, the upper case letter mean the projection pole is set in the southern
+definitions, the uppercase letter mean the projection pole is set in the southern
 hemisphere [Default is northern hemisphere]. Align the y-axis with the optional
 modifier **+v**. The figure size is set with *scale* or *width*.
 """

examples/projections/nongeo/cartesian_linear.py

@@ -4,7 +4,7 @@
 
 **X**\ *width*\ [/*height*] or **x**\ *x-scale*\ [/*y-scale*]
 
-Give the *width* of the figure and the optional *height*. The lower-case version
+Give the *width* of the figure and the optional *height*. The lowercase version
 **x** is similar to **X** but expects an *x-scale* and an optional *y-scale*.
 
 The Cartesian linear projection is primarily designed for regular floating point

examples/projections/nongeo/cartesian_logarithmic.py

@@ -6,7 +6,7 @@
 **x**\ *x-scale*\ [**l**][/*y-scale*\ [**l**]]
 
 Give the *width* of the figure and the optional *height*.
-The lower-case version **x** is similar to **X** but expects
+The lowercase version **x** is similar to **X** but expects
 an *x-scale* and an optional *y-scale*.
 Each axis with a logarithmic transformation requires **l** after
 its size argument.

examples/projections/nongeo/cartesian_power.py

@@ -6,7 +6,7 @@
 **x**\ *x-scale*\ [**p**\ *pvalue*][/*y-scale*\ [**p**\ *pvalue*]]
 
 Give the *width* of the figure and the optional argument *height*.
-The lower-case version **x** is similar to **X** but expects
+The lowercase version **x** is similar to **X** but expects
 an *x-scale* and an optional *y-scale*.
 Each axis with a power transformation requires **p** and the exponent
 for that axis after its size argument.

examples/projections/nongeo/polar.py

@@ -12,7 +12,7 @@
 
 Limits are set via the ``region`` parameter
 ([*theta_min*, *theta_max*, *radius_min*, *radius_max*]). When using **P**\ *width* you
-have to give the *width* of the figure. The lower-case version **p** is similar to **P**
+have to give the *width* of the figure. The lowercase version **p** is similar to **P**
 but expects a *scale* instead of a width (**p**\ *scale*).
 
 The following customizing modifiers are available: