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

Author: seisman

examples/tutorials/basics/coastlines.py

@@ -28,7 +28,7 @@
 # 4. lake-in-island-in-lake shore
 #
 # You can specify which level you want to plot by passing the level number and
-# a GMT pen configuration. For example, to plot just the coastlines with 0.5
+# a GMT pen configuration. For example, to plot just the coastlines with 0.5p
 # thickness and black lines:
 
 fig = pygmt.Figure()

pygmt/datasets/earth_age.py

@@ -32,19 +32,19 @@ def load_earth_age(resolution="01d", region=None, registration=None):
     ----------
     resolution : str
         The grid resolution. The suffix ``d`` and ``m`` stand for
-        arc-degree, arc-minute and arc-second. It can be ``'01d'``, ``'30m'``,
-        ``'20m'``, ``'15m'``, ``'10m'``, ``'06m'``, ``'05m'``, ``'04m'``,
-        ``'03m'``, ``'02m'``, or ``'01m'``.
+        arc-degree and arc-minute. It can be ``"01d"``, ``"30m"``,
+        ``"20m"``, ``"15m"``, ``"10m"``, ``"06m"``, ``"05m"``, ``"04m"``,
+        ``"03m"``, ``"02m"``, or ``"01m"``.
 
     region : str or list
         The subregion of the grid to load, in the forms of a list
         [*xmin*, *xmax*, *ymin*, *ymax*] or a string *xmin/xmax/ymin/ymax*.
         Required for grids with resolutions higher than 5
-        arc-minute (i.e., ``05m``).
+        arc-minute (i.e., ``"05m"``).
 
     registration : str
-        Grid registration type. Either ``pixel`` for pixel registration or
-        ``gridline`` for gridline registration. Default is ``None``, where
+        Grid registration type. Either ``"pixel"`` for pixel registration or
+        ``"gridline"`` for gridline registration. Default is ``None``, where
         a pixel-registered grid is returned unless only the
         gridline-registered grid is available.
 

pygmt/datasets/earth_relief.py

@@ -32,31 +32,31 @@ def load_earth_relief(resolution="01d", region=None, registration=None, use_srtm
     ----------
     resolution : str
         The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for
-        arc-degree, arc-minute and arc-second. It can be ``'01d'``, ``'30m'``,
-        ``'20m'``, ``'15m'``, ``'10m'``, ``'06m'``, ``'05m'``, ``'04m'``,
-        ``'03m'``, ``'02m'``, ``'01m'``, ``'30s'``, ``'15s'``, ``'03s'``,
-        or ``'01s'``.
+        arc-degree, arc-minute and arc-second. It can be ``"01d"``, ``"30m"``,
+        ``"20m"``, ``"15m"``, ``"10m"``, ``"06m"``, ``"05m"``, ``"04m"``,
+        ``"03m"``, ``"02m"``, ``"01m"``, ``"30s"``, ``"15s"``, ``"03s"``,
+        or ``"01s"``.
 
     region : str or list
         The subregion of the grid to load, in the forms of a list
         [*xmin*, *xmax*, *ymin*, *ymax*] or a string *xmin/xmax/ymin/ymax*.
         Required for Earth relief grids with resolutions higher than 5
-        arc-minute (i.e., ``05m``).
+        arc-minute (i.e., ``"05m"``).
 
     registration : str
-        Grid registration type. Either ``pixel`` for pixel registration or
-        ``gridline`` for gridline registration. Default is ``None``, where
+        Grid registration type. Either ``"pixel"`` for pixel registration or
+        ``"gridline"`` for gridline registration. Default is ``None``, where
         a gridline-registered grid is returned unless only the pixel-registered
         grid is available.
 
-        **Note:** For GMT 6.3, ``registration=None`` returns a pixel-registered
+        **Note**: For GMT 6.3, ``registration=None`` returns a pixel-registered
         grid by default unless only the gridline-registered grid is available.
 
     use_srtm : bool
         By default, the land-only SRTM tiles from NASA are used to generate the
-        ``'03s'`` and ``'01s'`` grids, and the missing ocean values are filled
+        ``"03s"`` and ``"01s"`` grids, and the missing ocean values are filled
         by up-sampling the SRTM15+ tiles which have a resolution of 15
-        arc-second (i.e., ``'15s'``). If True, will only load the original
+        arc-second (i.e., ``"15s"``). If True, will only load the original
         land-only SRTM tiles.
 
     Returns

pygmt/figure.py

@@ -59,8 +59,9 @@ class Figure:
     Examples
     --------
 
-    >>> fig = Figure()
-    >>> fig.basemap(region=[0, 360, -90, 90], projection="W7i", frame=True)
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 360, -90, 90], projection="W15c", frame=True)
     >>> fig.savefig("my-figure.png")
     >>> # Make sure the figure file is generated and clean it up
     >>> import os
@@ -71,8 +72,9 @@ class Figure:
     The plot region can be specified through ISO country codes (for example,
     ``'JP'`` for Japan):
 
-    >>> fig = Figure()
-    >>> fig.basemap(region="JP", projection="M3i", frame=True)
+    >>> import pygmt
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region="JP", projection="M7c", frame=True)
     >>> # The fig.region attribute shows the WESN bounding box for the figure
     >>> print(", ".join(f"{i:.2f}" for i in fig.region))
     122.94, 145.82, 20.53, 45.52

pygmt/helpers/decorators.py

@@ -309,9 +309,9 @@
               text, add the column **t**. Append the word number to **t** to
               write only a single word from the trailing text. Instead of
               specifying columns, use ``outcols="n"`` to simply read numerical
-              input and skip trailing text. Note: if ``incols`` is also used
-              then the columns given to ``outcols`` correspond to the order
-              after the ``incols`` selection has taken place.""",
+              input and skip trailing text. *Note**: If ``incols`` is also
+              used then the columns given to ``outcols`` correspond to the
+              order after the ``incols`` selection has taken place.""",
     "p": r"""
         perspective : list or str
             [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]\

pygmt/src/grd2cpt.py

@@ -86,10 +86,10 @@ def grd2cpt(grid, **kwargs):
     background : bool or str
         Select the back- and foreground colors to match the colors for lowest
         and highest *z*-values in the output CPT [Default (``background=True``
-        or ``background='o'``) uses the colors specified in the master file, or
+        or ``background="o"``) uses the colors specified in the master file, or
         those defined by the parameters :gmt-term:`COLOR_BACKGROUND`,
         :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN`]. Use
-        ``background='i'`` to match the colors for the lowest and highest
+        ``background="i"`` to match the colors for the lowest and highest
         values in the input (instead of the output) CPT.
     color_model :
         [**R**\|\ **r**\|\ **h**\|\ **c**][**+c**\ [*label*]].
@@ -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
@@ -153,7 +153,7 @@ def grd2cpt(grid, **kwargs):
         Do not interpolate the input color table but pick the output colors
         starting at the beginning of the color table, until colors for all
         intervals are assigned. This is particularly useful in combination with
-        a categorical color table, like ``cmap='categorical'``.
+        a categorical color table, like ``cmap="categorical"``.
     cyclic : bool
         Produce a wrapped (cyclic) color table that endlessly repeats its
         range. Note that ``cyclic=True`` cannot be set together with

pygmt/src/grdimage.py

@@ -95,10 +95,10 @@ def grdimage(self, grid, **kwargs):
         drivers. Append a **+c**\ *args* string where *args* is a list
         of one or more concatenated number of GDAL **-co** arguments. For
         example, to write a GeoPDF with the TerraGo format use
-        ``=PDF+cGEO_ENCODING=OGC_BP``. Notes: (1) If a tiff file (.tif) is
-        selected then we will write a GeoTiff image if the GMT projection
-        syntax translates into a PROJ syntax, otherwise a plain tiff file
-        is produced. (2) Any vector elements will be lost.
+        ``=PDF+cGEO_ENCODING=OGC_BP``. **Notes**: (1) If a tiff file (.tif)
+        is selected then we will write a GeoTiff image if the GMT
+        projection syntax translates into a PROJ syntax, otherwise a plain
+        tiff file is produced. (2) Any vector elements will be lost.
     {B}
     {CPT}
     img_in : str
@@ -138,9 +138,9 @@ def grdimage(self, grid, **kwargs):
         want a more specific intensity scenario then run
         :func:`pygmt.grdgradient` separately first. If we should derive
         intensities from another file than grid, specify the file with
-        suitable modifiers [Default is no illumination]. Note: If the input
-        data is an *image* then an *intensfile* or constant *intensity* must
-        be provided.
+        suitable modifiers [Default is no illumination]. **Note**: If the
+        input data is an *image* then an *intensfile* or constant *intensity*
+        must be provided.
     {J}
     monochrome : bool
         Force conversion to monochrome image using the (television) YIQ

pygmt/src/image.py

@@ -38,7 +38,7 @@ def image(self, imagefile, **kwargs):
         This must be an Encapsulated PostScript (EPS) file or a raster
         image. An EPS file must contain an appropriate BoundingBox. A
         raster file can have a depth of 1, 8, 24, or 32 bits and is read
-        via GDAL. Note: If GDAL was not configured during GMT installation
+        via GDAL. **Note**: If GDAL was not configured during GMT installation
         then only EPS files are supported.
     {J}
     {R}

pygmt/src/makecpt.py

@@ -66,19 +66,19 @@ def makecpt(**kwargs):
     ----------
     transparency : 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
         at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`.
     background : bool or str
         Select the back- and foreground colors to match the colors for lowest
         and highest *z*-values in the output CPT [Default (``background=True``
-        or ``background='o'``) uses the colors specified in the master file, or
+        or ``background="o"``) uses the colors specified in the master file, or
         those defined by the parameters :gmt-term:`COLOR_BACKGROUND`,
         :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN`]. Use
-        ``background='i'`` to match the colors for the lowest and highest
+        ``background="i"`` to match the colors for the lowest and highest
         values in the input (instead of the output) CPT.
     color_model :
         [**R**\|\ **r**\|\ **h**\|\ **c**][**+c**\ [*label*]].
@@ -89,9 +89,9 @@ def makecpt(**kwargs):
         appended then we create labels for each category to be used when the
         CPT is plotted. The *label* may be a comma-separated list of category
         names (you can skip a category by not giving a name), or give
-        *start*[-], where we automatically build monotonically increasing
-        labels from *start* (a single letter or an integer). Append - to build
-        ranges *start*-*start+1* instead.
+        *start*\[**-**], where we automatically build monotonically increasing
+        labels from *start* (a single letter or an integer). Append **-** to
+        build ranges *start*-*start+1* instead.
     series : list or str
         [*min/max/inc*\[**+b**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*].
         Defines the range of the new CPT by giving the lowest and highest
@@ -110,10 +110,10 @@ def makecpt(**kwargs):
         also :gmt-docs:`cookbook/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
-        file. If not given or False (default), saves the CPT as the session
+        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
+        Set this to True or **c** [Default] to reverse the sense of color
         progression in the master CPT. Set this to z to reverse the sign of
         z-values in the color table. Note that this change of z-direction
         happens before ``truncate`` and ``series`` values are used so the
@@ -140,7 +140,7 @@ def makecpt(**kwargs):
         Do not interpolate the input color table but pick the output colors
         starting at the beginning of the color table, until colors for all
         intervals are assigned. This is particularly useful in combination with
-        a categorical color table, like ``cmap='categorical'``.
+        a categorical color table, like ``cmap="categorical"``.
     cyclic : bool
         Produce a wrapped (cyclic) color table that endlessly repeats its
         range. Note that ``cyclic=True`` cannot be set together with

pygmt/src/project.py

@@ -141,7 +141,7 @@ def project(data=None, x=None, y=None, z=None, outfile=None, **kwargs):
         end point cannot be farther apart than :math:`2|\mbox{{colat}}|`.
         Finally, if you append **+h** then we will report the position of
         the pole as part of the segment header [Default is no header].
-        Note: No input is read and the value of ``data``, ``x``, ``y``,
+        **Note**: No input is read and the value of ``data``, ``x``, ``y``,
         and ``z`` is ignored if ``generate`` is used.
 
     length : str or list

pygmt/src/subplot.py

@@ -69,9 +69,9 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         follow sequentially. Surround the number or letter by parentheses on
         any side if these should be typeset as part of the tag. Use
         **+j**\|\ **J**\ *refpoint* to specify where the tag should be placed
-        in the subplot [TL]. Note: **+j** sets the justification of the tag to
-        *refpoint* (suitable for interior tags) while **+J** instead selects
-        the mirror opposite (suitable for exterior tags). Append
+        in the subplot [TL]. **Note**: **+j** sets the justification of the
+        tag to *refpoint* (suitable for interior tags) while **+J** instead
+        selects the mirror opposite (suitable for exterior tags). Append
         **+c**\ *dx*\[/*dy*] to set the clearance between the tag and a
         surrounding text box requested via **+g** or **+p** [3p/3p, i.e., 15%
         of the :gmt-term:`FONT_TAG` size dimension]. Append **+g**\ *fill* to
@@ -89,23 +89,24 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         Reserve a space of dimension *clearance* between the margin and the
         subplot on the specified side, using *side* values from **w**, **e**,
         **s**, or **n**; or **x** for both **w** and **e**; or **y** for both
-        **s** and **n**. No *side* means all sides (i.e. ``clearance='1c'``
+        **s** and **n**. No *side* means all sides (i.e. ``clearance="1c"``
         would set a clearance of 1 cm on all sides). The option is repeatable
-        to set aside space on more than one side (e.g. ``clearance=['w1c',
-        's2c']`` would set a clearance of 1 cm on west side and 2 cm on south
-        side). Such space will be left untouched by the main map plotting but
-        can be accessed by methods that plot scales, bars, text, etc.
+        to set aside space on more than one side (e.g.
+        ``clearance=["w1c", "s2c"]`` would set a clearance of 1 cm on west
+        side and 2 cm on south side). Such space will be left untouched by
+        the main map plotting but can be accessed by methods that plot
+        scales, bars, text, etc.
     {J}
     margins : str or list
         This is margin space that is added between neighboring subplots (i.e.,
         the interior margins) in addition to the automatic space added for tick
         marks, annotations, and labels. The margins can be specified as either:
 
-        - a single value (for same margin on all sides). E.g. '5c'.
+        - a single value (for same margin on all sides). E.g. ``"5c"``.
         - a pair of values (for setting separate horizontal and vertical
-          margins). E.g. ['5c', '3c'].
+          margins). E.g. ``["5c", "3c"]``.
         - a set of four values (for setting separate left, right, bottom, and
-          top margins). E.g. ['1c', '2c', '3c', '4c'].
+          top margins). E.g. ``["1c", "2c", "3c", "4c"]``.
 
         The actual gap created is always a sum of the margins for the two
         opposing sides (e.g., east plus west or south plus north margins)
@@ -116,7 +117,7 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         Set subplot layout for shared x-axes. Use when all subplots in a column
         share a common *x*-range. If ``sharex=True``, the first (i.e.,
         **t**\ op) and the last (i.e., **b**\ ottom) rows will have
-        *x*-annotations; use ``sharex='t'`` or ``sharex='b'`` to select only
+        *x*-annotations; use ``sharex="t"`` or ``sharex="b"`` to select only
         one of those two rows [both]. Append **+l** if annotated *x*-axes
         should have a label [none]; optionally append the label if it is the
         same for the entire subplot. Append **+t** to make space for subplot
@@ -126,7 +127,7 @@ def subplot(self, nrows=1, ncols=1, **kwargs):
         Set subplot layout for shared y-axes. Use when all subplots in a row
         share a common *y*-range. If ``sharey=True``, the first (i.e.,
         **l**\ eft) and the last (i.e., **r**\ ight) columns will have
-        *y*-annotations; use ``sharey='l'`` or ``sharey='r'`` to select only
+        *y*-annotations; use ``sharey="l"`` or ``sharey="r"`` to select only
         one of those two columns [both]. Append **+l** if annotated *y*-axes
         will have a label [none]; optionally, append the label if it is the
         same for the entire subplot. Append **+p** to make all annotations
@@ -173,13 +174,13 @@ def set_panel(self, panel=None, **kwargs):
     r"""
     Set the current subplot panel to plot on.
 
-    Before you start plotting you must first select the active subplot. Note:
-    If any *projection* option is passed with the question mark **?** as scale
-    or width when plotting subplots, then the dimensions of the map are
-    automatically determined by the subplot size and your region. For Cartesian
-    plots: If you want the scale to apply equally to both dimensions then you
-    must specify ``projection="x"`` [The default ``projection="X"`` will fill
-    the subplot by using unequal scales].
+    Before you start plotting you must first select the active subplot.
+    **Note**: If any *projection* option is passed with the question mark
+    **?** as scale or width when plotting subplots, then the dimensions of
+    the map are automatically determined by the subplot size and your
+    region. For Cartesian plots: If you want the scale to apply equally to
+    both dimensions then you must specify ``projection="x"`` [The default
+    ``projection="X"`` will fill the subplot by using unequal scales].
 
     {aliases}
 
@@ -208,7 +209,7 @@ def set_panel(self, panel=None, **kwargs):
         Reserve a space of dimension *clearance* between the margin and the
         subplot on the specified side, using *side* values from **w**, **e**,
         **s**, or **n**. The option is repeatable to set aside space on more
-        than one side (e.g. ``clearance=['w1c', 's2c']`` would set a clearance
+        than one side (e.g. ``clearance=["w1c", "s2c"]`` would set a clearance
         of 1 cm on west side and 2 cm on south side). Such space will be left
         untouched by the main map plotting but can be accessed by methods that
         plot scales, bars, text, etc. This setting overrides the common