docs: Various docstring fixes related to parameter markup (#5869)

I've batched here some queued commits that addresses various small warnings, or just to continue aligning the docstrings with other places.

Some of the fixes here seemed to have originated from copy-paste errors, and a few are real typos too.
Using admonitions (boxes) for "Attention: " rendered quite nice and colourful, so I kept it.
Escaping a trailing underscore in the parameter list is necessary as it was interpreted as a label, so then the parameters weren't matching the signature, when using some stricter warnings. And the backslash needs to be escaped too, as one is for python to keep the backslash, the second one to pass to sphinx/docutils.  So, `:param xxxx_: bla bla bla` into `:param xxxx\\_: bla bla bla`

When finding issues, I was doing searches on the repo to find other cases. Usually I was skipping the gui folder, as I wasn't building the docs for it, but this time I let one slip.

There was one parameter that I didn't know how to document, as the previous text was completely unrelated (copy-paste error).

* docs: Fix indent of return of grass.grassdb.read()

* docs: Fix docstring formatting of grass.jupyter.interactivemap

* docs: Fix param syntax of grass.script.core

* docs: Use attention admonitions in docstrings of grass.pygrass.gis.region

* docs: Use double backticks for inline code style in grass.script.core

* docs: Replace `<tt></tt>` markup with double backticks in docstrings

* docs: Use double backticks for inline code style in docstrings of grass.script.core and grass.script.raster3d

* docs: Fix some invalid parameter list generating warnings

* docs: Fix note syntax in grass.jupyter.interactivemap.InteractiveMap.add_raster()

* docs: Fix typos in described parameter not matching the signature

* docs: Escape parameters ending with underscores in docstrings

* docs: Add or remove parameters in docstrings that don't belong to the functions in grass.temporal

Probably copy paste errors

* docs: Remove contradicting type in param list of python/grass/script/utils.py

* docs: Add LineDist return type in docstring of grass.pygrass.vector.geometry.Line.distance()

* docs: Fill in docstring for grass.script.utils.text_to_string()

Author: echoix

gui/wxpython/iscatt/dialogs.py

@@ -234,7 +234,7 @@ def __init__(
         """Dialog for export of category raster.
 
         :param parent: window
-        :param str rasterName name of vector layer for export
+        :param str rasterName: name of vector layer for export
         :param title: window title
         """
         wx.Dialog.__init__(self, parent, id, title, style=style, **kwargs)

python/grass/grassdb/history.py

@@ -130,8 +130,7 @@ def read(history_path):
     """Read the content of the history file.
 
     :param str history_path: path to the history log file
-    :return content_list: list of dictionaries
-    with 'command' and 'command_info' keys
+    :return content_list: list of dictionaries with 'command' and 'command_info' keys
     """
     if get_history_file_extension(history_path) == ".json":
         return _read_from_JSON(history_path)

python/grass/jupyter/interactivemap.py

@@ -63,12 +63,12 @@ def __init__(
     ):
         """Reproject GRASS raster, export to PNG, and compute bounding box.
 
-        param str name: layer name
-        param str title: title of layer to display in layer control legend
-        param bool use_region: use computational region of current mapset
-        param str saved_region: name of saved computation region
-        param renderer: instance of ReprojectionRenderer
-        **kwargs: keyword arguments passed to folium/ipyleaflet layer instance
+        :param str name: layer name
+        :param str title: title of layer to display in layer control legend
+        :param bool use_region: use computational region of current mapset
+        :param str saved_region: name of saved computation region
+        :param renderer: instance of ReprojectionRenderer
+        :param kwargs: keyword arguments passed to folium/ipyleaflet layer instance
         """
         self._name = name
         self._layer_kwargs = kwargs
@@ -355,10 +355,11 @@ def add_raster(self, name, title=None, **kwargs):
         Color table for the raster can be modified with `r.colors` before calling
         this function.
 
-        .. note:: This will only work if the raster is located in the current mapset.
-        To change the color table of a raster located outside the current mapset,
-        switch to that mapset with `g.mapset`, modify the color table with `r.color`
-        then switch back to the initial mapset and run this function.
+        .. note::
+            This will only work if the raster is located in the current mapset.
+            To change the color table of a raster located outside the current mapset,
+            switch to that mapset with ``g.mapset``, modify the color table with ``r.color``
+            then switch back to the initial mapset and run this function.
 
         :param str name: name of raster to add to display; positional-only parameter
         :param str title: raster name for layer control
@@ -372,7 +373,8 @@ def add_layer_control(self, **kwargs):
 
         A Layer Control is added by default. Call this function to customize
         layer control object. Accepts keyword arguments to be passed to leaflet
-        layer control object"""
+        layer control object
+        """
 
         if self._folium:
             self.layer_control_object = self._folium.LayerControl(**kwargs)

python/grass/pygrass/gis/region.py

@@ -459,7 +459,7 @@ def set_raster_region(self):
         """Set the computational region (window) for all raster maps in the current
         process.
 
-        Attention: All raster objects must be closed or the
+        .. Attention:: All raster objects must be closed or the
                    process will be terminated.
 
         The Raster library C function Rast_set_window() is called.
@@ -498,7 +498,7 @@ def set_current(self):
         This function adjusts the values before setting the region
         so you don't have to call G_adjust_Cell_head().
 
-        Attention: Only the current process is affected.
+        .. Attention:: Only the current process is affected.
                    The GRASS computational region is not affected.
 
         :Example:

python/grass/pygrass/modules/grid/grid.py

@@ -410,8 +410,8 @@ class GridModule:
     :type mapset_prefix: str
     :param patch_backend: "r.patch", "RasterRow", or None for for default
     :type patch_backend: None or str
-    :param run_: if False only instantiate the object
-    :type run_: bool
+    :param run\\_: if False only instantiate the object
+    :type run\\_: bool
     :param args: give all the parameters to the command
     :param kargs: give all the parameters to the command
 

python/grass/pygrass/raster/__init__.py

@@ -693,7 +693,7 @@ def numpy2raster(array, mtype, rastname, overwrite=False):
 
     :param obj array: a numpy array
     :param obj mtype: the datatype of array
-    :param str rastername: the name of output map
+    :param str rastname: the name of output map
     :param bool overwrite: True to overwrite existing map
     """
     reg = Region()

python/grass/pygrass/vector/basic.py

@@ -198,8 +198,8 @@ def append(self, box):
         """Append a Bbox object to a Boxlist object, using the
         ``Vect_boxlist_append`` C function.
 
-        :param bbox: the bounding box to add to the list
-        :param bbox: a Bbox object
+        :param box: the bounding box to add to the list
+        :type box: a Bbox object
 
         >>> box0 = Bbox()
         >>> box1 = Bbox(1, 2, 3, 4)

python/grass/pygrass/vector/find.py

@@ -30,7 +30,7 @@ def __init__(
         :param c_mapinfo: Pointer to the vector layer mapinfo structure
         :type c_mapinfo: ctypes pointer to mapinfo structure
         :param table: Attribute table of the vector layer
-        :param writable: True or False
+        :param writeable: True or False
         """
         self.c_mapinfo = c_mapinfo
         self.table: Table | None = table

python/grass/pygrass/vector/geometry.py

@@ -594,8 +594,8 @@ def buffer(
         :type dist_y: num
         :param angle: the angle between 0x and major axis
         :type angle: num
-        :param round_: to make corners round
-        :type round_: bool
+        :param round\\_: to make corners round
+        :type round\\_: bool
         :param tol: fix the maximum distance between theoretical arc and output segments
         :type tol: float
         :returns: the buffer as Area object
@@ -892,6 +892,7 @@ def distance(self, pnt):
 
         :param pnt: the point to calculate distance
         :type pnt: a Point object or a tuple with the coordinates
+        :rtype: LineDist
 
         Return a namedtuple with:
 
@@ -1173,8 +1174,8 @@ def buffer(
         :type dist_y: num
         :param angle: the angle between 0x and major axis
         :type angle: num
-        :param round_: to make corners round
-        :type round_: bool
+        :param round\\_: to make corners round
+        :type round\\_: bool
         :param tol: fix the maximum distance between theoretical arc and output segments
         :type tol: float
         :returns: the buffer as Area object
@@ -1734,8 +1735,8 @@ def buffer(
         :type dist_y: num
         :param angle: the angle between 0x and major axis
         :type angle: num
-        :param round_: to make corners round
-        :type round_: bool
+        :param round\\_: to make corners round
+        :type round\\_: bool
         :param tol: fix the maximum distance between theoretical arc and output segments
         :type tol: float
         :returns: the buffer as line, centroid, isles object tuple

python/grass/script/core.py

@@ -267,10 +267,10 @@ def make_command(
 
     :param str prog: GRASS module
     :param str flags: flags to be used (given as a string)
-    :param bool overwrite: True to enable overwriting the output (<tt>--o</tt>)
-    :param bool quiet: True to run quietly (<tt>--q</tt>)
-    :param bool superquiet: True to run extra quietly (<tt>--qq</tt>)
-    :param bool verbose: True to run verbosely (<tt>--v</tt>)
+    :param bool overwrite: True to enable overwriting the output (``--o``)
+    :param bool quiet: True to run quietly (``--q``)
+    :param bool superquiet: True to run extra quietly (``--qq``)
+    :param bool verbose: True to run verbosely (``--v``)
     :param options: module's parameters
 
     :return: list of arguments
@@ -444,10 +444,10 @@ def start_command(
 
     :param str prog: GRASS module
     :param str flags: flags to be used (given as a string)
-    :param bool overwrite: True to enable overwriting the output (<tt>--o</tt>)
-    :param bool quiet: True to run quietly (<tt>--q</tt>)
-    :param bool superquiet: True to run extra quietly (<tt>--qq</tt>)
-    :param bool verbose: True to run verbosely (<tt>--v</tt>)
+    :param bool overwrite: True to enable overwriting the output (``--o``)
+    :param bool quiet: True to run quietly (``--q``)
+    :param bool superquiet: True to run extra quietly (``--qq``)
+    :param bool verbose: True to run verbosely (``--v``)
     :param kwargs: module's parameters
 
     :return: Popen object
@@ -490,8 +490,8 @@ def run_command(*args, **kwargs):
     The behavior on error can be changed using *errors* parameter
     which is passed to the :func:`handle_errors()` function.
 
-    :param *args: unnamed arguments passed to :func:`start_command()`
-    :param **kwargs: named arguments passed to :func:`start_command()`
+    :param args: unnamed arguments passed to :func:`start_command()`
+    :param kwargs: named arguments passed to :func:`start_command()`
     :param str errors: passed to :func:`handle_errors()`
 
     .. versionchanged:: 8.0
@@ -717,10 +717,10 @@ def exec_command(
 
     :param str prog: GRASS module
     :param str flags: flags to be used (given as a string)
-    :param bool overwrite: True to enable overwriting the output (<tt>--o</tt>)
-    :param bool quiet: True to run quietly (<tt>--q</tt>)
-    :param bool superquiet: True to run quietly (<tt>--qq</tt>)
-    :param bool verbose: True to run verbosely (<tt>--v</tt>)
+    :param bool overwrite: True to enable overwriting the output (``--o``)
+    :param bool quiet: True to run quietly (``--q``)
+    :param bool superquiet: True to run quietly (``--qq``)
+    :param bool verbose: True to run verbosely (``--v``)
     :param env: dictionary with system environment variables
                 (:external:py:data:`os.environ` by default)
     :param list kwargs: module's parameters
@@ -748,11 +748,11 @@ def message(msg, flag=None, env=None):
 
 
 def debug(msg, debug=1, env=None):
-    """Display a debugging message using `g.message -d`.
+    """Display a debugging message using ``g.message -d``.
 
     The visibility of a debug message at runtime is controlled by
-    setting the corresponding DEBUG level with `g.gisenv set="DEBUG=X"`
-    (with `X` set to the debug level specified in the function call).
+    setting the corresponding DEBUG level with ``g.gisenv set="DEBUG=X"``
+    (with ``X`` set to the debug level specified in the function call).
 
     :param str msg: debugging message to be displayed
     :param str debug: debug level (0-5) with the following recommended
@@ -772,7 +772,7 @@ def debug(msg, debug=1, env=None):
 
 
 def verbose(msg, env=None):
-    """Display a verbose message using `g.message -v`
+    """Display a verbose message using ``g.message -v``
 
     :param str msg: verbose message to be displayed
     :param env: dictionary with system environment variables
@@ -782,7 +782,7 @@ def verbose(msg, env=None):
 
 
 def info(msg, env=None):
-    """Display an informational message using `g.message -i`
+    """Display an informational message using ``g.message -i``
 
     :param str msg: informational message to be displayed
     :param env: dictionary with system environment variables
@@ -792,7 +792,7 @@ def info(msg, env=None):
 
 
 def percent(i, n, s, env=None):
-    """Display a progress info message using `g.message -p`
+    """Display a progress info message using ``g.message -p``
 
     .. code-block:: python
 
@@ -812,7 +812,7 @@ def percent(i, n, s, env=None):
 
 
 def warning(msg, env=None):
-    """Display a warning message using `g.message -w`
+    """Display a warning message using ``g.message -w``
 
     :param str msg: warning message to be displayed
     :param env: dictionary with system environment variables
@@ -822,7 +822,7 @@ def warning(msg, env=None):
 
 
 def error(msg, env=None):
-    """Display an error message using `g.message -e`
+    """Display an error message using ``g.message -e``
 
     This function does not end the execution of the program.
     The right action after the error is up to the caller.
@@ -836,7 +836,7 @@ def error(msg, env=None):
 
 
 def fatal(msg, env=None):
-    """Display an error message using `g.message -e`, then abort or raise
+    """Display an error message using ``g.message -e``, then abort or raise
 
     Raises exception when module global raise_on_error is 'True', abort
     (calls :external:py:func:`sys.exit`) otherwise.
@@ -1102,7 +1102,7 @@ def _text_to_key_value_dict(
     checkunits: bool = False,
 ) -> KeyValue[list[int | float | str]]:
     """Convert a key-value text file, where entries are separated by newlines
-    and the key and value are separated by `sep', into a key-value dictionary
+    and the key and value are separated by ``sep``, into a key-value dictionary
     and discover/use the correct data types (float, int or string) for values.
 
     :param filename: The name or name and path of the text file to convert
@@ -1199,7 +1199,7 @@ def compare_key_value_text_files(
         d : hello,8,0.1
 
     :param str filename_a: name of the first key-value text file
-    :param str filenmae_b: name of the second key-value text file
+    :param str filename_b: name of the second key-value text file
     :param str sep: character that separates the keys and values, default is ":"
     :param str val_sep: character that separates the values of a single key,
                         default is ","
@@ -1677,7 +1677,7 @@ def parse_color(
     val: str, dflt: tuple[float, float, float] | None = None
 ) -> tuple[float, float, float] | None:
     """Parses the string "val" as a GRASS colour, which can be either one of
-    the named colours or an R:G:B tuple e.g. 255:255:255. Returns an
+    the named colours or an ``R:G:B`` tuple e.g. ``255:255:255``. Returns an
     (r,g,b) triple whose components are floating point values between 0
     and 1.
 
@@ -1728,7 +1728,7 @@ def verbosity():
 
     2 all messages will be printed
 
-    3 also verbose messages will be printed. Triggered by "--v" or "--verbose" flag.
+    3 also verbose messages will be printed. Triggered by "``--v``" or "``--verbose``" flag.
     """
     vbstr = os.getenv("GRASS_VERBOSE")
     if vbstr:
@@ -1744,8 +1744,8 @@ def find_program(pgm, *args):
 
     You must call the program in a way that will return a successful
     exit code. For GRASS modules this means you need to pass it some
-    valid CLI option, like "--help". For other programs a common
-    valid do-little option is usually "--version".
+    valid CLI option, like "``--help``". For other programs a common
+    valid do-little option is usually "``--version``".
 
     :Example:
       .. code-block:: pycon