fmt_docstrings: Use string template syntax for docstring placeholders and support curly braces in docstrings (#4210)

* fmt_docstrings: Use string.Template for docstring placeholders
* Update docstring placeholders to the string.Template syntax
* Update {aliases} to $aliases and {table-classes} to $table_classes
* Replace {{/}} with {/} in LaTeX math equations

Author: seisman

pygmt/helpers/decorators.py

@@ -6,6 +6,7 @@
 """
 
 import functools
+import string
 import textwrap
 import warnings
 from inspect import Parameter, signature
@@ -410,11 +411,11 @@ def fmt_docstring(module_func):
     ...     ----------
     ...     data
     ...         Pass in either a file name to an ASCII data table, a 2-D
-    ...         {table-classes}.
-    ...     {region}
-    ...     {projection}
+    ...         $table_classes.
+    ...     $region
+    ...     $projection
     ...
-    ...     {aliases}
+    ...     $aliases
     ...     '''
     ...     pass
     >>> print(gmtinfo.__doc__)
@@ -456,7 +457,7 @@ def fmt_docstring(module_func):
             aliases.append(f"   - {arg} = {alias}")
         filler_text["aliases"] = "\n".join(aliases)
 
-    filler_text["table-classes"] = (
+    filler_text["table_classes"] = (
         ":class:`numpy.ndarray`, a :class:`pandas.DataFrame`, an\n"
         "    :class:`xarray.Dataset` made up of 1-D :class:`xarray.DataArray`\n"
         "    data variables, or a :class:`geopandas.GeoDataFrame` containing the\n"
@@ -471,8 +472,7 @@ def fmt_docstring(module_func):
     # Dedent the docstring to make it all match the option text.
     docstring = textwrap.dedent(module_func.__doc__)
 
-    module_func.__doc__ = docstring.format(**filler_text)
-
+    module_func.__doc__ = string.Template(docstring).safe_substitute(**filler_text)
     return module_func
 
 

pygmt/src/basemap.py

@@ -45,7 +45,7 @@ def basemap(
 
     Full GMT docs at :gmt-docs:`basemap.html`.
 
-    {aliases}
+    $aliases
        - B = frame
        - J = projection
        - Jz = zscale
@@ -58,12 +58,12 @@ def basemap(
 
     Parameters
     ----------
-    {projection}
+    $projection
     zscale/zsize
         Set z-axis scaling or z-axis size.
-    {region}
+    $region
         *Required if this is the first plot command.*
-    {frame}
+    $frame
     map_scale : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *length*.
@@ -92,11 +92,11 @@ def basemap(
     compass : str
         Draw a map magnetic rose on the map at the location defined by the
         reference and anchor points.
-    {verbose}
-    {panel}
-    {coltypes}
-    {perspective}
-    {transparency}
+    $verbose
+    $panel
+    $coltypes
+    $perspective
+    $transparency
     """
     self._activate_figure()
 

pygmt/src/binstats.py

@@ -65,7 +65,7 @@ def binstats(
 
     Full GMT docs at :gmt-docs:`gmtbinstats.html`.
 
-    {aliases}
+    $aliases
        - C = statistic
        - I = spacing
        - R = region
@@ -76,8 +76,8 @@ def binstats(
     Parameters
     ----------
     data
-        A file name of an ASCII data table or a 2-D {table-classes}.
-    {outgrid}
+        A file name of an ASCII data table or a 2-D $table_classes.
+    $outgrid
     statistic
         Choose the statistic that will be computed per node based on the points that are
         within *radius* distance of the node. Select one of:
@@ -116,14 +116,14 @@ def binstats(
         computed while the count will be the sum of the weights instead of
         number of points. If the weights are actually uncertainties
         (one sigma) then append **+s** and weight = 1/sigma.
-    {spacing}
-    {region}
-    {verbose}
-    {aspatial}
-    {binary}
-    {header}
-    {incols}
-    {registration}
+    $spacing
+    $region
+    $verbose
+    $aspatial
+    $binary
+    $header
+    $incols
+    $registration
 
     Returns
     -------

pygmt/src/blockm.py

@@ -111,7 +111,7 @@ def blockmean(  # noqa: PLR0913
 
     Full GMT docs at :gmt-docs:`blockmean.html`.
 
-    {aliases}
+    $aliases
        - I = spacing
        - R = region
        - V = verbose
@@ -124,12 +124,12 @@ def blockmean(  # noqa: PLR0913
     data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
-        {table-classes}.
+        $table_classes.
     x/y/z : 1-D arrays
         Arrays of x and y coordinates and values z of the data points.
-    {output_type}
-    {outfile}
-    {spacing}
+    $output_type
+    $outfile
+    $spacing
     summary : str
         [**m**\|\ **n**\|\ **s**\|\ **w**].
         Type of summary values calculated by blockmean.
@@ -138,18 +138,18 @@ def blockmean(  # noqa: PLR0913
         - **n**: report the number of input points inside each block
         - **s**: report the sum of all z-values inside a block
         - **w**: report the sum of weights
-    {region}
-    {verbose}
-    {aspatial}
-    {binary}
-    {nodata}
-    {find}
-    {incols}
-    {coltypes}
-    {header}
-    {outcols}
-    {registration}
-    {wrap}
+    $region
+    $verbose
+    $aspatial
+    $binary
+    $nodata
+    $find
+    $incols
+    $coltypes
+    $header
+    $outcols
+    $registration
+    $wrap
 
     Returns
     -------
@@ -226,7 +226,7 @@ def blockmedian(  # noqa: PLR0913
 
     Full GMT docs at :gmt-docs:`blockmedian.html`.
 
-    {aliases}
+    $aliases
        - I = spacing
        - R = region
        - V = verbose
@@ -239,24 +239,24 @@ def blockmedian(  # noqa: PLR0913
     data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
-        {table-classes}.
+        $table_classes.
     x/y/z : 1-D arrays
         Arrays of x and y coordinates and values z of the data points.
-    {output_type}
-    {outfile}
-    {spacing}
-    {region}
-    {verbose}
-    {aspatial}
-    {binary}
-    {nodata}
-    {find}
-    {coltypes}
-    {header}
-    {incols}
-    {outcols}
-    {registration}
-    {wrap}
+    $output_type
+    $outfile
+    $spacing
+    $region
+    $verbose
+    $aspatial
+    $binary
+    $nodata
+    $find
+    $coltypes
+    $header
+    $incols
+    $outcols
+    $registration
+    $wrap
 
     Returns
     -------
@@ -341,7 +341,7 @@ def blockmode(  # noqa: PLR0913
 
     Full GMT docs at :gmt-docs:`blockmode.html`.
 
-    {aliases}
+    $aliases
        - I = spacing
        - R = region
        - V = verbose
@@ -354,24 +354,24 @@ def blockmode(  # noqa: PLR0913
     data
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2-D
-        {table-classes}.
+        $table_classes.
     x/y/z : 1-D arrays
         Arrays of x and y coordinates and values z of the data points.
-    {output_type}
-    {outfile}
-    {spacing}
-    {region}
-    {verbose}
-    {aspatial}
-    {binary}
-    {nodata}
-    {find}
-    {coltypes}
-    {header}
-    {incols}
-    {outcols}
-    {registration}
-    {wrap}
+    $output_type
+    $outfile
+    $spacing
+    $region
+    $verbose
+    $aspatial
+    $binary
+    $nodata
+    $find
+    $coltypes
+    $header
+    $incols
+    $outcols
+    $registration
+    $wrap
 
     Returns
     -------

pygmt/src/coast.py

@@ -66,7 +66,7 @@ def coast(
 
     Full GMT docs at :gmt-docs:`coast.html`.
 
-    {aliases}
+    $aliases
        - B = frame
        - D = resolution
        - F = box
@@ -79,11 +79,11 @@ def coast(
 
     Parameters
     ----------
-    {projection}
-    {region}
+    $projection
+    $region
         *Required if this is the first plot command.*
-    {area_thresh}
-    {frame}
+    $area_thresh
+    $frame
     lakes : str or list
         *fill*\ [**+l**\|\ **+r**].
         Set the shade, color, or pattern for lakes and river-lakes. The
@@ -172,10 +172,10 @@ def coast(
         to any of the continent codes (e.g. ``"=EU"`` for Europe). Append
         **+p**\ *pen* to draw polygon outlines [Default is no outline] and
         **+g**\ *fill* to fill them [Default is no fill].
-    {panel}
-    {perspective}
-    {transparency}
-    {verbose}
+    $panel
+    $perspective
+    $transparency
+    $verbose
 
     Example
     -------

pygmt/src/colorbar.py

@@ -44,7 +44,7 @@ def colorbar(  # noqa: PLR0913
     .. note::
        For GMT >=6.5.0, the fontsizes of the colorbar x-label, x-annotations,
        and y-label are scaled based on the width of the colorbar following
-       :math:`\sqrt{{colorbar\_width / 15}}`. To set a desired fontsize via the
+       :math:`\sqrt{colorbar\_width / 15}`. To set a desired fontsize via the
        GMT default parameters :gmt-term:`FONT_ANNOT_PRIMARY`,
        :gmt-term:`FONT_ANNOT_SECONDARY`, and :gmt-term:`FONT_LABEL` (or jointly
        :gmt-term:`FONT`) users have to divide the desired fontsize by the value
@@ -54,7 +54,7 @@ def colorbar(  # noqa: PLR0913
 
     Full GMT docs at :gmt-docs:`colorbar.html`.
 
-    {aliases}
+    $aliases
        - B = frame
        - F = box
        - G = truncate
@@ -70,7 +70,7 @@ def colorbar(  # noqa: PLR0913
     ----------
     frame : str or list
         Set colorbar boundary frame, labels, and axes attributes.
-    {cmap}
+    $cmap
     position : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         [**+w**\ *length*\ [/\ *width*]]\ [**+e**\ [**b**\|\ **f**][*length*]]\
@@ -134,10 +134,10 @@ def colorbar(  # noqa: PLR0913
         may be in plot distance units or given as relative fractions and will
         be automatically scaled so that the sum of the widths equals the
         requested colorbar length.
-    {verbose}
-    {panel}
-    {perspective}
-    {transparency}
+    $verbose
+    $panel
+    $perspective
+    $transparency
 
     Example
     -------