DOC: Make bullet point lists consistent in docstrings (":" and lower-…

…case) Part I (#3572)

pygmt/src/binstats.py

@@ -43,33 +43,31 @@ def binstats(data, outgrid: str | None = None, **kwargs) -> xr.DataArray | None:
     Parameters
     ----------
     data : str, {table-like}
-        A file name of an ASCII data table or a 2-D
-        {table-classes}.
+        A file name of an ASCII data table or a 2-D {table-classes}.
     {outgrid}
     statistic : str
         **a**\|\ **d**\|\ **g**\|\ **i**\|\ **l**\|\ **L**\|\ **m**\|\ **n**\
         \|\ **o**\|\ **p**\|\ **q**\ [*quant*]\|\ **r**\|\ **s**\|\ **u**\
         \|\ **U**\|\ **z**.
         Choose the statistic that will be computed per node based on the
-        points that are within *radius* distance of the node.  Select one of:
+        points that are within *radius* distance of the node. Select one of:
 
-        - **a** for mean (average)
-        - **d** for median absolute deviation (MAD)
-        - **g** for full (max-min) range
-        - **i** for 25-75% interquartile range
-        - **l** for minimum (low)
-        - **L** for minimum of positive values only
-        - **m** for median
-        - **n** the number of values
-        - **o** for LMS scale
-        - **p** for mode (maximum likelihood)
-        - **q** for selected quantile (append desired quantile in
-          0-100% range [50])
-        - **r** for the r.m.s.
-        - **s** for standard deviation
-        - **u** for maximum (upper)
-        - **U** for maximum of negative values only
-        - **z** for the sum
+        - **a**: mean (average)
+        - **d**: median absolute deviation (MAD)
+        - **g**: full (max-min) range
+        - **i**: 25-75% interquartile range
+        - **l**: minimum (low)
+        - **L**: minimum of positive values only
+        - **m**: median
+        - **n**: number of values
+        - **o**: LMS scale
+        - **p**: mode (maximum likelihood)
+        - **q**: selected quantile (append desired quantile in 0-100% range [50])
+        - **r**: root mean square (RMS)
+        - **s**: standard deviation
+        - **u**: maximum (upper)
+        - **U**: maximum of negative values only
+        - **z**: sum
     empty : float
         Set the value assigned to empty nodes [Default is NaN].
     normalize : bool

pygmt/src/blockm.py

@@ -126,10 +126,10 @@ def blockmean(
         [**m**\|\ **n**\|\ **s**\|\ **w**].
         Type of summary values calculated by blockmean.
 
-        - **m** - reports mean value [Default]
-        - **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
+        - **m**: reports mean value [Default]
+        - **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}

pygmt/src/coast.py

@@ -87,26 +87,26 @@ def coast(self, **kwargs):
         Choose from the list of river types below; pass a list to ``rivers``
         to use multiple arguments.
 
-        - ``0``: Double-lined rivers (river-lakes)
-        - ``1``: Permanent major rivers
-        - ``2``: Additional major rivers
-        - ``3``: Additional rivers
-        - ``4``: Minor rivers
-        - ``5``: Intermittent rivers - major
-        - ``6``: Intermittent rivers - additional
-        - ``7``: Intermittent rivers - minor
-        - ``8``: Major canals
-        - ``9``: Minor canals
-        - ``10``: Irrigation canals
+        - ``0``: double-lined rivers (river-lakes)
+        - ``1``: permanent major rivers
+        - ``2``: additional major rivers
+        - ``3``: additional rivers
+        - ``4``: minor rivers
+        - ``5``: intermittent rivers - major
+        - ``6``: intermittent rivers - additional
+        - ``7``: intermittent rivers - minor
+        - ``8``: major canals
+        - ``9``: minor canals
+        - ``10``: irrigation canals
 
         You can also choose from several preconfigured river groups:
 
-        - ``"a"``: All rivers and canals (0-10)
-        - ``"A"``: All rivers and canals except river-lakes (1-10)
-        - ``"r"``: All permanent rivers (0-4)
-        - ``"R"``: All permanent rivers except river-lakes (1-4)
-        - ``"i"``: All intermittent rivers (5-7)
-        - ``"c"``: All canals (8-10)
+        - ``"a"``: rivers and canals (``0`` - ``10``)
+        - ``"A"``: rivers and canals except river-lakes (``1`` - ``10``)
+        - ``"r"``: permanent rivers (``0`` - ``4``)
+        - ``"R"``: permanent rivers except river-lakes (``1`` - ``4``)
+        - ``"i"``: intermittent rivers (``5`` - ``7``)
+        - ``"c"``: canals (``8`` - ``10``)
 
     map_scale : str
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*.
@@ -137,10 +137,10 @@ def coast(self, **kwargs):
         Choose from the list of boundaries below. Pass a list to ``borders`` to
         use multiple arguments.
 
-        - ``1``: National boundaries
-        - ``2``: State boundaries within the Americas
-        - ``3``: Marine boundaries
-        - ``"a"``: All boundaries (1-3)
+        - ``1``: national boundaries
+        - ``2``: state boundaries within the Americas
+        - ``3``: marine boundaries
+        - ``"a"``: all boundaries (``1`` - ``3``)
 
     water : str
         Select filling "wet" areas.

pygmt/src/dimfilter.py

@@ -51,34 +51,32 @@ def dimfilter(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None
     distance : int or str
         Distance flag tells how grid (x,y) relates to filter width, as follows:
 
-        - **0**\ : grid (x,y) in same units as *width*, Cartesian distances.
-        - **1**\ : grid (x,y) in degrees, *width* in kilometers, Cartesian
-          distances.
-        - **2**\ : grid (x,y) in degrees, *width* in km, dx scaled by
-          cos(middle y), Cartesian distances.
+        - **0**: grid (x,y) in same units as *width*, Cartesian distances.
+        - **1**: grid (x,y) in degrees, *width* in kilometers, Cartesian distances.
+        - **2**: grid (x,y) in degrees, *width* in km, dx scaled by cos(middle y),
+          Cartesian distances.
 
         The above options are fastest because they allow weight matrix to be
         computed only once. The next two options are slower because they
         recompute weights for each latitude.
 
-        - **3**\ : grid (x,y) in degrees, *width* in km, dx scaled by
-          cosine(y), Cartesian distance calculation.
-        - **4**\ : grid (x,y) in degrees, *width* in km, Spherical distance
-          calculation.
+        - **3**: grid (x,y) in degrees, *width* in km, dx scaled by cosine(y),
+          Cartesian distance calculation.
+        - **4**: grid (x,y) in degrees, *width* in km, Spherical distance calculation.
     filter : str
         **x**\ *width*\ [**+l**\|\ **u**].
         Set the primary filter type. Choose among convolution and
         non-convolution filters. Use the filter code **x** followed by
         the full diameter *width*. Available convolution filters are:
 
-        - (**b**) Boxcar: All weights are equal.
-        - (**c**) Cosine Arch: Weights follow a cosine arch curve.
-        - (**g**) Gaussian: Weights are given by the Gaussian function.
+        - **b**: boxcar. Aall weights are equal.
+        - **c**: cosine arch. Weights follow a cosine arch curve.
+        - **g**: Gaussian. Weights are given by the Gaussian function.
 
         Non-convolution filters are:
 
-        - (**m**) Median: Returns median value.
-        - (**p**) Maximum likelihood probability (a mode estimator): Return
+        - **m**: median. Returns median value.
+        - **p**: maximum likelihood probability (a mode estimator). Return
           modal value. If more than one mode is found we return their average
           value. Append **+l** or **+h** to the filter width if you want
           to return the smallest or largest of each sector's modal values.
@@ -89,11 +87,11 @@ def dimfilter(grid, outgrid: str | None = None, **kwargs) -> xr.DataArray | None
         set to 1, the secondary filter is not effective. Available secondary
         filters **x** are:
 
-        - (**l**) Lower: Return the minimum of all filtered values.
-        - (**u**) Upper: Return the maximum of all filtered values.
-        - (**a**) Average: Return the mean of all filtered values.
-        - (**m**) Median: Return the median of all filtered values.
-        - (**p**) Mode: Return the mode of all filtered values:
+        - **l**: lower. Return the minimum of all filtered values.
+        - **u**: upper. Return the maximum of all filtered values.
+        - **a**: average. Return the mean of all filtered values.
+        - **m**: median. Return the median of all filtered values.
+        - **p**: mode. Return the mode of all filtered values.
           If more than one mode is found we return their average
           value. Append **+l** or **+h** to the sectors if you rather want to
           return the smallest or largest of the modal values.

pygmt/src/filter1d.py

@@ -57,23 +57,23 @@ def filter1d(
 
         Available convolution filter types are:
 
-        - (**b**) Boxcar: All weights are equal.
-        - (**c**) Cosine Arch: Weights follow a cosine arch curve.
-        - (**g**) Gaussian: Weights are given by the Gaussian function.
-        - (**f**) Custom: Instead of *width* give name of a one-column file
+        - **b**: boxcar. All weights are equal.
+        - **c**: cosine arch. Weights follow a cosine arch curve.
+        - **g**: Gaussian. Weights are given by the Gaussian function.
+        - **f**: custom. Instead of *width* give name of a one-column file
           with your own weight coefficients.
 
         Non-convolution filter types are:
 
-        - (**m**) Median: Returns median value.
-        - (**p**) Maximum likelihood probability (a mode estimator): Return
+        - **m**: median. Returns median value.
+        - **p**: maximum likelihood probability (a mode estimator). Return
           modal value. If more than one mode is found we return their average
           value. Append **+l** or **+u** if you rather want
           to return the lowermost or uppermost of the modal values.
-        - (**l**) Lower: Return the minimum of all values.
-        - (**L**) Lower: Return minimum of all positive values only.
-        - (**u**) Upper: Return maximum of all values.
-        - (**U**) Upper: Return maximum of all negative values only.
+        - **l**: lower (absolute). Return the minimum of all values.
+        - **L**: lower. Return minimum of all positive values only.
+        - **u**: upper (absolute). Return maximum of all values.
+        - **U**: upper. Return maximum of all negative values only.
 
         Upper case type **B**, **C**, **G**, **M**, **P**, **F** will use
         robust filter versions: i.e., replace outliers (2.5 L1 scale off

pygmt/src/grd2xyz.py

@@ -96,17 +96,17 @@ def grd2xyz(
         appending **y**. If the byte-order needs to be swapped, append
         **w**. Select one of several data types (all binary except **a**):
 
-        * **a** ASCII representation of a single item per record
-        * **c** int8_t, signed 1-byte character
-        * **u** uint8_t, unsigned 1-byte character
-        * **h** int16_t, short 2-byte integer
-        * **H** uint16_t, unsigned short 2-byte integer
-        * **i** int32_t, 4-byte integer
-        * **I** uint32_t, unsigned 4-byte integer
-        * **l** int64_t, long (8-byte) integer
-        * **L** uint64_t, unsigned long (8-byte) integer
-        * **f** 4-byte floating point single precision
-        * **d** 8-byte floating point double precision
+        - **a**: ASCII representation of a single item per record
+        - **c**: int8_t, signed 1-byte character
+        - **u**: uint8_t, unsigned 1-byte character
+        - **h**: int16_t, short 2-byte integer
+        - **H**: uint16_t, unsigned short 2-byte integer
+        - **i**: int32_t, 4-byte integer
+        - **I**: uint32_t, unsigned 4-byte integer
+        - **l**: int64_t, long (8-byte) integer
+        - **L**: uint64_t, unsigned long (8-byte) integer
+        - **f**: 4-byte floating point single precision
+        - **d**: 8-byte floating point double precision
 
         Default format is scanline orientation of ASCII numbers: **TLa**.
     {binary}