Merge branch 'main' into test-old-gmt-versions

Author: seisman

.github/workflows/ci_docs.yml

@@ -79,7 +79,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.22.0
+        uses: dawidd6/action-download-artifact@v2.23.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests.yaml

@@ -101,7 +101,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.22.0
+        uses: dawidd6/action-download-artifact@v2.23.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests_dev.yaml

@@ -131,7 +131,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.22.0
+        uses: dawidd6/action-download-artifact@v2.23.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/dvc-diff.yml

@@ -19,7 +19,7 @@ jobs:
         fetch-depth: 0
 
     - name: Setup data version control (DVC)
-      uses: iterative/[email protected].3
+      uses: iterative/[email protected].4
 
     - name: Setup continuous machine learning (CML)
       uses: iterative/[email protected]

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

@@ -19,7 +19,7 @@ jobs:
       uses: actions/[email protected]
 
     - name: Setup data version control (DVC)
-      uses: iterative/[email protected].3
+      uses: iterative/[email protected].4
 
     - name: Pull baseline image data from dvc remote
       run: |

.readthedocs.yaml

@@ -6,7 +6,7 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
     python: "mambaforge-4.10"
   jobs:

Makefile

@@ -4,11 +4,7 @@ TESTDIR=tmp-test-dir-with-unique-name
 PYTEST_COV_ARGS=--cov=$(PROJECT) --cov-config=../pyproject.toml \
 			--cov-report=term-missing --cov-report=xml --cov-report=html \
 			--pyargs ${PYTEST_EXTRA}
-BLACK_FILES=$(PROJECT) doc/conf.py examples
-BLACKDOC_OPTIONS=--line-length 79
-DOCFORMATTER_FILES=$(PROJECT) doc/conf.py examples
-DOCFORMATTER_OPTIONS=--recursive --pre-summary-newline --make-summary-multi-line --wrap-summaries 79 --wrap-descriptions 79
-FLAKEHEAVEN_FILES=$(PROJECT) doc/conf.py examples
+FORMAT_FILES=$(PROJECT) doc/conf.py examples
 LINT_FILES=$(PROJECT) doc/conf.py
 
 help:
@@ -70,16 +66,16 @@ test_no_images:
 
 format:
 	isort .
-	docformatter --in-place $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
-	black $(BLACK_FILES)
-	blackdoc $(BLACKDOC_OPTIONS) $(BLACK_FILES)
+	docformatter --in-place $(FORMAT_FILES)
+	black $(FORMAT_FILES)
+	blackdoc $(FORMAT_FILES)
 
 check:
 	isort . --check
-	docformatter --check $(DOCFORMATTER_OPTIONS) $(DOCFORMATTER_FILES)
-	black --check $(BLACK_FILES)
-	blackdoc --check $(BLACKDOC_OPTIONS) $(BLACK_FILES)
-	FLAKEHEAVEN_CACHE_TIMEOUT=0 flakeheaven lint $(FLAKEHEAVEN_FILES)
+	docformatter --check $(FORMAT_FILES)
+	black --check $(FORMAT_FILES)
+	blackdoc --check $(FORMAT_FILES)
+	FLAKEHEAVEN_CACHE_TIMEOUT=0 flakeheaven lint $(FORMAT_FILES)
 
 lint:
 	pylint $(LINT_FILES)

doc/contributing.md

@@ -392,13 +392,14 @@ Guidelines for a good tutorial:
   concise examples while the tutorials are detailed and full of text.
 * SI units should be used in the example code for tutorial plots.
 
-Note that the `Figure.show()` method needs to be called for a plot to be inserted into
-the documentation.
+Note that the <code>pygmt.Figure.show</code> method needs to be called for a plot
+to be inserted into the documentation.
+
 
 ### Editing the API Documentation
 
 The API documentation is built from the docstrings in the Python `*.py` files under
-the `pygmt/src/` and `/pygmt/datasets/` folders. **All docstrings** should follow the
+the `pygmt/src/` and `pygmt/datasets/` folders. **All docstrings** should follow the
 [NumPy style guide](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
 All functions/classes/methods should have docstrings with a full description of all
 arguments and return values.
@@ -524,9 +525,9 @@ Tests also help us be confident that we won't break your code in the future.
 
 When writing tests, don't test everything that the GMT function already tests, such as
 the every unique combination arguments. An exception to this would be the most popular
-methods, such as `plot` and `basemap`. The highest priority for tests should be the
-Python-specific code, such as numpy, pandas, and xarray objects and the virtualfile
-mechanism.
+methods, such as <code>pygmt.Figure.plot</code> and <code>pygmt.Figure.basemap</code>.
+The highest priority for tests should be the Python-specific code, such as numpy,
+pandas, and xarray objects and the virtualfile mechanism.
 
 If you're **new to testing**, see existing test files for examples of things to do.
 **Don't let the tests keep you from submitting your contribution!**

environment.yml

@@ -22,7 +22,7 @@ dependencies:
     # Dev dependencies (style checks)
     - black
     - blackdoc
-    - docformatter
+    - docformatter>=1.5.0
     - flakeheaven>=3
     - isort>=5
     - pylint

examples/gallery/maps/land_and_water.py

@@ -5,8 +5,8 @@
 The ``land`` and ``water`` parameters of :meth:`pygmt.Figure.coast` specify
 a color to fill in the land and water masses, respectively. There are many
 :gmt-docs:`color codes in GMT <gmtcolors.html>`, including standard GMT color
-names (like ``skyblue``), R/G/B levels (like ``0/0/255``), a hex value (like
-``#333333``), and a graylevel (like ``50``).
+names (like ``"skyblue"``), R/G/B levels (like ``"0/0/255"``), a hex value
+(like ``"#333333"``), and a gray level (like ``"gray50"``).
 """
 import pygmt
 

pygmt/figure.py

@@ -147,7 +147,7 @@ def psconvert(self, icc_gray=False, **kwargs):
 
         If no input files are given, will convert the current active figure
         (see :class:`pygmt.Figure`). In this case, an output name must be given
-        using parameter *prefix*.
+        using parameter ``prefix``.
 
         Full option list at :gmt-docs:`psconvert.html`
 
@@ -289,6 +289,10 @@ def savefig(
         dpi : int
             Set raster resolution in dpi. Default is 720 for PDF, 300 for
             others.
+        **kwargs : dict
+            Additional keyword arguments passed to
+            :meth:`pygmt.Figure.psconvert`. Valid parameters are ``gs_path``,
+            ``gs_option``, ``resize``, ``bb_style``, and ``verbose``.
         """
         # All supported formats
         fmts = dict(png="g", pdf="f", jpg="j", bmp="b", eps="e", tif="t", kml="g")
@@ -319,7 +323,7 @@ def savefig(
         if show:
             launch_external_viewer(fname)
 
-    def show(self, dpi=300, width=500, method=None, waiting=0.5):
+    def show(self, dpi=300, width=500, method=None, waiting=0.5, **kwargs):
         """
         Display a preview of the figure.
 
@@ -361,6 +365,10 @@ def show(self, dpi=300, width=500, method=None, waiting=0.5):
             Suspend the execution of the current process for a given number of
             seconds after launching an external viewer.
             Only works if ``method="external"``.
+        **kwargs : dict
+            Additional keyword arguments passed to
+            :meth:`pygmt.Figure.psconvert`. Valid parameters are ``gs_path``,
+            ``gs_option``, ``resize``, ``bb_style``, and ``verbose``.
         """
         # Module level variable to know which figures had their show method
         # called. Needed for the sphinx-gallery scraper.
@@ -387,11 +395,15 @@ def show(self, dpi=300, width=500, method=None, waiting=0.5):
                         "or run the script in a Jupyter notebook."
                     )
                 )
-            png = self._preview(fmt="png", dpi=dpi, anti_alias=True, as_bytes=True)
+            png = self._preview(
+                fmt="png", dpi=dpi, anti_alias=True, as_bytes=True, **kwargs
+            )
             IPython.display.display(IPython.display.Image(data=png, width=width))
 
         if method == "external":
-            pdf = self._preview(fmt="pdf", dpi=dpi, anti_alias=False, as_bytes=False)
+            pdf = self._preview(
+                fmt="pdf", dpi=dpi, anti_alias=False, as_bytes=False, **kwargs
+            )
             launch_external_viewer(pdf, waiting=waiting)
 
     def shift_origin(self, xshift=None, yshift=None):

pygmt/src/dimfilter.py

@@ -40,8 +40,8 @@ def dimfilter(grid, **kwargs):
     subregion of the input and/or with a new increment using ``spacing``,
     which may add an "extra space" in the input data to prevent edge
     effects for the output grid. If the filter is low-pass, then the output
-    may be less frequently sampled than the input. **dimfilter** will not
-    produce a smooth output as other spatial filters
+    may be less frequently sampled than the input. :func:`pygmt.dimfilter`
+    will not produce a smooth output as other spatial filters
     do because it returns a minimum median out of *N* medians of *N*
     sectors. The output can be rough unless the input data is noise-free.
     Thus, an additional filtering (e.g., Gaussian via :func:`pygmt.grdfilter`)

pygmt/src/grd2cpt.py

@@ -56,16 +56,16 @@ def grd2cpt(grid, **kwargs):
     If the master CPT includes B, F, and N entries, these will be copied into
     the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
     :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
-    :gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
-    default behavior can be overruled using the options ``background``,
-    ``overrule_bg`` or ``no_bg``.
+    :gmt-docs:`gmt.conf <gmt.conf>` file will be used. This default behavior
+    can be overruled using the parameters ``background``, ``overrule_bg``
+    or ``no_bg``.
 
     The color model (RGB, HSV or CMYK) of the palette created by
     :func:`pygmt.grd2cpt` will be the same as specified in the header of the
     master CPT. When there is no :gmt-term:`COLOR_MODEL` entry in the master
     CPT, the :gmt-term:`COLOR_MODEL` specified in the
-    :gmt-docs:`gmt.conf <gmt.conf>` file or the ``color_model`` option will be
-    used.
+    :gmt-docs:`gmt.conf <gmt.conf>` file or the ``color_model`` parameter
+    will be used.
 
     Full option list at :gmt-docs:`grd2cpt.html`
 
@@ -77,8 +77,8 @@ def grd2cpt(grid, **kwargs):
         The file name of the input grid or the grid loaded as a DataArray.
     transparency : int or float or str
         Sets a constant level of transparency (0-100) for all color slices.
-        Append **+a** to also affect the fore-, back-, and nan-colors
-        [Default is no transparency, i.e., 0 (opaque)].
+        Append **+a** to also affect the foreground, background, and NaN
+        colors [Default is no transparency, i.e., 0 (opaque)].
     cmap : str
         Selects the master color palette table (CPT) to use in the
         interpolation. Full list of built-in color palette tables can be found
@@ -124,7 +124,7 @@ def grd2cpt(grid, **kwargs):
         also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     output : str
         Optional parameter to set the file name with extension .cpt to store
-        the generated CPT file. If not given or False (default), saves the CPT
+        the generated CPT file. If not given or False (Default), saves the CPT
         as the session current CPT.
     reverse : str
         Set this to True or c [Default] to reverse the sense of color
@@ -137,8 +137,8 @@ def grd2cpt(grid, **kwargs):
         Overrule background, foreground, and NaN colors specified in the master
         CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
         :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
-        the :gmt-docs:`gmt.conf <gmt.conf>` file or on the command line. When
-        combined with ``background``, only :gmt-term:`COLOR_NAN` is considered.
+        the :gmt-docs:`gmt.conf <gmt.conf>` file. When combined with
+        ``background``, only :gmt-term:`COLOR_NAN` is considered.
     no_bg : bool
         Do not write out the background, foreground, and NaN-color fields
         [Default will write them, i.e. ``no_bg=False``].

pygmt/src/grdgradient.py

@@ -84,7 +84,7 @@ def grdgradient(grid, **kwargs):
         [**m**\|\ **s**\|\ **p**]\ *azim/elev*\ [**+a**\ *ambient*][**+d**\
         *diffuse*][**+p**\ *specular*][**+s**\ *shine*].
         Compute Lambertian radiance appropriate to use with
-        :doc:`pygmt.Figure.grdimage` and :doc:`pygmt.Figure.grdview`. The
+        :meth:`pygmt.Figure.grdimage` and :meth:`pygmt.Figure.grdview`. The
         Lambertian Reflection assumes an ideal surface that reflects all the
         light that strikes it and the surface appears
         equally bright from all viewing directions. Here, *azim* and *elev* are

pygmt/src/grdimage.py

@@ -50,11 +50,11 @@ def grdimage(self, grid, **kwargs):
     instructions to derive intensities from the input data grid. Values outside
     this range will be clipped. Such intensity files can be created from the
     grid using :func:`pygmt.grdgradient` and, optionally, modified by
-    ``grdmath`` or ``grdhisteq``. If GMT is built with GDAL support, ``grid``
-    can be an image file (geo-referenced or not). In this case the image can
-    optionally be illuminated with the file provided via the ``shading``
-    parameter. Here, if image has no coordinates then those of the intensity
-    file will be used.
+    :gmt-docs:`grdmath.html` or :class:`pygmt.grdhisteq`. If GMT is built
+    with GDAL support, ``grid`` can be an image file (geo-referenced or not).
+    In this case the image can optionally be illuminated with the file
+    provided via the ``shading`` parameter. Here, if image has no coordinates
+    then those of the intensity file will be used.
 
     When using map projections, the grid is first resampled on a new
     rectangular grid with the same dimensions. Higher resolution images can

pygmt/src/makecpt.py

@@ -48,15 +48,15 @@ def makecpt(**kwargs):
     If the master CPT includes B, F, and N entries, these will be copied into
     the new master file. If not, the parameters :gmt-term:`COLOR_BACKGROUND`,
     :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` from the
-    :gmt-docs:`gmt.conf <gmt.conf>` file or the command line will be used. This
+    :gmt-docs:`gmt.conf <gmt.conf>` file will be used. This
     default behavior can be overruled using the parameters ``background``,
     ``overrule_bg`` or ``no_bg``.
 
-    The color model (RGB, HSV or CMYK) of the palette created by **makecpt**
-    will be the same as specified in the header of the master CPT. When there
-    is no :gmt-term:`COLOR_MODEL` entry in the master CPT, the
-    :gmt-term:`COLOR_MODEL` specified in the :gmt-docs:`gmt.conf <gmt.conf>`
-    file or on the command line will be used.
+    The color model (RGB, HSV or CMYK) of the palette created by
+    :func:`pygmt.makecpt` will be the same as specified in the header of the
+    master CPT. When there is no :gmt-term:`COLOR_MODEL` entry in the
+    master CPT, the :gmt-term:`COLOR_MODEL` specified in the
+    :gmt-docs:`gmt.conf <gmt.conf>` file will be used.
 
     Full option list at :gmt-docs:`makecpt.html`
 
@@ -123,14 +123,14 @@ def makecpt(**kwargs):
         Overrule background, foreground, and NaN colors specified in the master
         CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
         :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
-        the :gmt-docs:`gmt.conf <gmt.conf>` file or on the command line. When
-        combined with **background**, only :gmt-term:`COLOR_NAN` is considered.
+        the :gmt-docs:`gmt.conf <gmt.conf>` file. When combined with
+        ``background``, only :gmt-term:`COLOR_NAN` is considered.
     no_bg : bool
         Do not write out the background, foreground, and NaN-color fields
         [Default will write them, i.e. ``no_bg=False``].
     log : bool
         For logarithmic interpolation scheme with input given as logarithms.
-        Expects input z-values provided via **series** to be log10(*z*),
+        Expects input z-values provided via ``series`` to be log10(*z*),
         assigns colors, and writes out *z*.
     continuous : bool
         Force a continuous CPT when building from a list of colors and a list

pygmt/src/meca.py

@@ -204,7 +204,7 @@ def meca(
         ``event_name`` values in ``spec`` if ``spec`` is a dict or
         pd.DataFrame.
     offset: bool or str
-        [**+p**\ *pen*][**+s**\ *size].
+        [**+p**\ *pen*][**+s**\ *size*].
         Offsets beachballs to the longitude, latitude specified in the last two
         columns of the input file or array, or by ``plot_longitude`` and
         ``plot_latitude`` if provided. A small circle is plotted at the initial