[GRASS-git] [OSGeo/grass] c4e18c: docs: Various docstring fixes related to parameter...

[Edouard Choinière]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: c4e18c1871d9aca398cfb791ff00a7114624eb14
      https://github.com/OSGeo/grass/commit/c4e18c1871d9aca398cfb791ff00a7114624eb14
  Author: Edouard Choinière <27212526+echoix at users.noreply.github.com>
  Date:   2025-06-10 (Tue, 10 Jun 2025)

  Changed paths:
    M gui/wxpython/iscatt/dialogs.py
    M python/grass/grassdb/history.py
    M python/grass/jupyter/interactivemap.py
    M python/grass/pygrass/gis/region.py
    M python/grass/pygrass/modules/grid/grid.py
    M python/grass/pygrass/raster/__init__.py
    M python/grass/pygrass/vector/basic.py
    M python/grass/pygrass/vector/find.py
    M python/grass/pygrass/vector/geometry.py
    M python/grass/script/core.py
    M python/grass/script/raster.py
    M python/grass/script/raster3d.py
    M python/grass/script/utils.py
    M python/grass/temporal/base.py
    M python/grass/temporal/core.py
    M python/grass/temporal/stds_export.py
    M python/grass/temporal/temporal_algebra.py
    M python/grass/temporal/temporal_raster_base_algebra.py

  Log Message:
  -----------
  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()



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications