Merge branch 'master' into wrap-grd2cpt

Author: willschlitzer

.github/dependabot.yml

@@ -0,0 +1,17 @@
+# Set update schedule for GitHub Actions
+
+version: 2
+updates:
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every weekday
+      interval: "weekly"
+      day: "tuesday"
+    # Allow up to 2 open pull requests at a time
+    open-pull-requests-limit: 2
+    # Specify labels for pull requests
+    labels:
+      - "maintenance"
+      - "skip-changelog"

.github/workflows/format-command.yml

@@ -21,7 +21,7 @@ jobs:
           ref: ${{ github.event.client_payload.pull_request.head.ref }}
 
       # Setup Python environment
-      - uses: actions/setup-python@v1
+      - uses: actions/setup-python@v2.2.1
 
       # Install formatting tools
       - name: Install formatting tools

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

@@ -28,7 +28,7 @@ jobs:
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v2.2.1
       with:
         python-version: 3.9
 
@@ -52,13 +52,13 @@ jobs:
         ls -lh dist/
 
     - name: Publish to Test PyPI
-      uses: pypa/gh-action-pypi-publish@v1.4.1
+      uses: pypa/gh-action-pypi-publish@v1.4.2
       with:
         password: ${{ secrets.test_pypi_password }}
         repository_url: https://test.pypi.org/legacy/
 
     - name: Publish to PyPI
       if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@v1.4.1
+      uses: pypa/gh-action-pypi-publish@v1.4.2
       with:
         password: ${{ secrets.pypi_password }}

.github/workflows/style_checks.yaml

@@ -20,7 +20,7 @@ jobs:
 
       # Setup Miniconda
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v2.2.1
         with:
           python-version: 3.9
 

pygmt/helpers/decorators.py

@@ -13,111 +13,124 @@
 from pygmt.helpers.utils import is_nonstr_iter
 
 COMMON_OPTIONS = {
-    "R": """\
+    "R": r"""
         region : str or list
             *Required if this is the first plot command*.
-            ``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
+            *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
             Specify the region of interest.""",
-    "J": """\
+    "J": r"""
         projection : str
             *Required if this is the first plot command*.
+            *projcode*\[*projparams*/]\ *width*.
             Select map projection.""",
-    "B": """\
-        frame : str or list
+    "B": r"""
+        frame : bool or str or list
             Set map boundary frame and axes attributes.""",
     "U": """\
         timestamp : bool or str
             Draw GMT time stamp logo on plot.""",
-    "CPT": """\
+    "CPT": r"""
         cmap : str
-           File name of a CPT file or ``C='color1,color2[,color3,...]'`` to
-           build a linear continuous CPT from those colors automatically.""",
+           File name of a CPT file or a series of comma-separated colors
+           (e.g., *color1*,\ *color2*,\ *color3*) to build a linear continuous
+           CPT from those colors automatically.""",
     "G": """\
         color : str
             Select color or pattern for filling of symbols or polygons. Default
             is no fill.""",
     "V": """\
-        verbose : str
-            Select verbosity level [Default is w], which modulates the messages
+        verbose : bool or str
+            Select verbosity level [Default is **w**], which modulates the messages
             written to stderr. Choose among 7 levels of verbosity:
 
             - **q** - Quiet, not even fatal error messages are produced
             - **e** - Error messages only
             - **w** - Warnings [Default]
             - **t** - Timings (report runtimes for time-intensive algorthms);
-            - **i** - Informational messages (same as "verbose=True")
+            - **i** - Informational messages (same as ``verbose=True``)
             - **c** - Compatibility warnings
             - **d** - Debugging messages""",
     "W": """\
         pen : str
             Set pen attributes for lines or the outline of symbols.""",
-    "XY": """\
+    "XY": r"""
         xshift : str
-            ``[a|c|f|r][xshift]``.
+            [**a**\|\ **c**\|\ **f**\|\ **r**\][*xshift*].
             Shift plot origin in x-direction.
         yshift : str
-            ``[a|c|f|r][yshift]``.
+            [**a**\|\ **c**\|\ **f**\|\ **r**\][*yshift*].
             Shift plot origin in y-direction. Full documentation is at
             :gmt-docs:`gmt.html#xy-full`.
          """,
-    "j": """\
+    "c": r"""
+        panel : bool or int or list
+            [*row,col*\|\ *index*].
+            Selects a specific subplot panel. Only allowed when in subplot
+            mode. Use ``panel=True`` to advance to the next panel in the
+            selected order. Instead of *row,col* you may also give a scalar
+            value *index* which depends on the order you set via ``autolabel``
+            when the subplot was defined. **Note**: *row*, *col*, and *index*
+            all start at 0.
+         """,
+    "j": r"""
         distcalc : str
-            ``e|f|g``.
+            **e**\|\ **f**\|\ **g**.
             Determine how spherical distances are calculated.
 
             - **e** - Ellipsoidal (or geodesic) mode
             - **f** - Flat Earth mode
             - **g** - Great circle distance [Default]
 
             All spherical distance calculations depend on the current ellipsoid
-            (PROJ_ELLIPSOID), the definition of the mean radius
-            (PROJ_MEAN_RADIUS), and the specification of latitude type
-            (PROJ_AUX_LATITUDE). Geodesic distance calculations is also
-            controlled by method (PROJ_GEODESIC).""",
-    "n": """\
+            (:gmt-term:`PROJ_ELLIPSOID`), the definition of the mean radius
+            (:gmt-term:`PROJ_MEAN_RADIUS`), and the specification of latitude type
+            (:gmt-term:`PROJ_AUX_LATITUDE`). Geodesic distance calculations is also
+            controlled by method (:gmt-term:`PROJ_GEODESIC`).""",
+    "n": r"""
         interpolation : str
-            ``[b|c|l|n][+a][+bBC][+c][+tthreshold]``
+            [**b**\|\ **c**\|\ **l**\|\ **n**][**+a**][**+b**\ *BC*][**+c**][**+t**\ *threshold*].
             Select interpolation mode for grids. You can select the type of
             spline used:
 
-            - 'b' for B-spline
-            - 'c' for bicubic [Default]
-            - 'l' for bilinear
-            - 'n' for nearest-neighbor""",
-    "p": """\
+            - **b** for B-spline
+            - **c** for bicubic [Default]
+            - **l** for bilinear
+            - **n** for nearest-neighbor""",
+    "p": r"""
         perspective : list or str
-            ``'[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'``.
+            [**x**\|\ **y**\|\ **z**]\ *azim*\[/*elev*\[/*zlevel*]]
+            [**+w**\ *lon0*/*lat0*\[/*z0*]][**+v**\ *x0*/*y0*].
             Select perspective view and set the azimuth and elevation angle of
             the viewpoint. Default is [180, 90]. Full documentation is at
             :gmt-docs:`gmt.html#perspective-full`.
         """,
-    "registration": """\
+    "registration": r"""
         registration : str
-            ``[g|p]``
+            **g**\|\ **p**.
             Force output grid to be gridline (g) or pixel (p) node registered.
             Default is gridline (g).""",
     "t": """\
-        transparency : float
+        transparency : int or float
             Set transparency level, in [0-100] percent range.
             Default is 0, i.e., opaque.
             Only visible when PDF or raster format output is selected.
             Only the PNG format selection adds a transparency layer
             in the image (for further processing). """,
-    "x": """\
-        cores : int
-            ``[[-]n]``.
+    "x": r"""
+        cores : bool or int
+            [[**-**]\ *n*].
             Limit the number of cores to be used in any OpenMP-enabled
             multi-threaded algorithms. By default we try to use all available
             cores. Set a number *n* to only use n cores (if too large it will
             be truncated to the maximum cores available). Finally, give a
-            negative number *-n* to select (all - n) cores (or at least 1 if
-            n equals or exceeds all).
+            negative number *-n* to select (all - *n*) cores (or at least 1 if
+            *n* equals or exceeds all).
             """,
 }
 
 
 def fmt_docstring(module_func):
-    """
+    r"""
     Decorator to insert common text into module docstrings.
 
     Should be the last decorator (at the top).
@@ -173,10 +186,11 @@ def fmt_docstring(module_func):
     ----------
     region : str or list
         *Required if this is the first plot command*.
-        ``'xmin/xmax/ymin/ymax[+r][+uunit]'``.
+        *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
         Specify the region of interest.
     projection : str
         *Required if this is the first plot command*.
+        *projcode*\[*projparams*/]\ *width*.
         Select map projection.
     <BLANKLINE>
     **Aliases:**
@@ -195,9 +209,9 @@ def fmt_docstring(module_func):
         filler_text["aliases"] = "\n".join(aliases)
 
     for marker, text in COMMON_OPTIONS.items():
-        # Remove the indentation from the multiline strings so that it doesn't
-        # mess up the original docstring
-        filler_text[marker] = textwrap.dedent(text)
+        # Remove the indentation and the first line break from the multiline
+        # strings so that it doesn't mess up the original docstring
+        filler_text[marker] = textwrap.dedent(text.lstrip("\n"))
 
     # Dedent the docstring to make it all match the option text.
     docstring = textwrap.dedent(module_func.__doc__)

pygmt/src/basemap.py

@@ -27,10 +27,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def basemap(self, **kwargs):
     """
     Plot base maps and frames for the figure.
@@ -66,13 +67,14 @@ def basemap(self, **kwargs):
     {U}
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
-    if not args_in_kwargs(args=["B", "L", "Td", "Tm"], kwargs=kwargs):
+    if not args_in_kwargs(args=["B", "L", "Td", "Tm", "c"], kwargs=kwargs):
         raise GMTInvalidInput(
-            "At least one of frame, map_scale, compass, or rose must be specified."
+            "At least one of frame, map_scale, compass, rose, or panel must be specified."
         )
     with Session() as lib:
         lib.call_module("basemap", build_arg_string(kwargs))

pygmt/src/coast.py

@@ -32,10 +32,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def coast(self, **kwargs):
     r"""
     Plot continents, shorelines, rivers, and borders on maps
@@ -182,6 +183,7 @@ def coast(self, **kwargs):
         the segment headers via **-Z**\ *code* settings.To apply different
         settings to different countries, pass a list of string arguments.
     {XY}
+    {c}
     {p}
     {t}
     {V}

pygmt/src/colorbar.py

@@ -20,10 +20,13 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
+@kwargs_to_strings(
+    R="sequence", G="sequence", I="sequence", c="sequence_comma", p="sequence"
+)
 def colorbar(self, **kwargs):
     """
     Plot a gray or color scale-bar on maps.
@@ -94,6 +97,7 @@ def colorbar(self, **kwargs):
         illumination.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """

pygmt/src/contour.py

@@ -30,10 +30,11 @@
     V="verbose",
     X="xshift",
     Y="yshift",
+    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def contour(self, x=None, y=None, z=None, data=None, **kwargs):
     """
     Contour table data by direct triangulation.
@@ -92,6 +93,7 @@ def contour(self, x=None, y=None, z=None, data=None, **kwargs):
         separator for the two labels instead.
     {V}
     {XY}
+    {c}
     {p}
     {t}
     """

pygmt/src/grdcontour.py

@@ -30,10 +30,13 @@
     l="label",
     X="xshift",
     Y="yshift",
+    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", L="sequence", A="sequence_plus", p="sequence")
+@kwargs_to_strings(
+    R="sequence", L="sequence", A="sequence_plus", c="sequence_comma", p="sequence"
+)
 def grdcontour(self, grid, **kwargs):
     """
     Convert grids or images to contours and plot them on maps.
@@ -87,6 +90,7 @@ def grdcontour(self, grid, **kwargs):
     {V}
     {W}
     {XY}
+    {c}
     label : str
         Add a legend entry for the contour being plotted. Normally, the
         annotated contour is selected for the legend. You can select the