From e8e21264e5380626454959ec4f19d058ea03933a Mon Sep 17 00:00:00 2001 From: Vaclav Petras Date: Mon, 13 Jul 2026 16:33:11 -0400 Subject: [PATCH] docs: Fix reStructuredText markup in Python docstrings The Sphinx build of the Python API documentation reports docutils warnings and errors for docstrings with invalid reStructuredText, and the affected docstrings also render badly. Fix the markup without changing the documented content: - grass.pydispatch.dispatcher: mark the two attribute listings as literal blocks, so that their plain-text layout is preserved instead of being misparsed as definition lists and block quotes. - grass.pygrass.raster.abstract: drop the literal block marker in front of the doctest example of Info, so that the example is parsed as a doctest block. The expected output lines are not prefixed with ">>>", which made the quoting of the literal block inconsistent. - grass.pygrass.vector.geometry: turn the parameter descriptions of the Node constructor into an actual field list. - grass.gunittest.runner, grass.pygrass.vector.geometry, grass.tools.session_tools: escape or quote the asterisks so that "**kwargs" is not parsed as the start of inline strong markup. - grass.imaging.images2avi: indent the continuation line of the bg_task field body, so that the field list is not cut short. - grass.temporal.core: indent the content of the warning directive in init(), so that the directive is not empty. This brings the number of warnings and errors reported by the Sphinx build down from 42 to 19. Each fixed docstring is reported twice because the subpackages are currently documented under two names. The fixes were prepared with the help of Claude Code (AI) and verified against the rendered HTML pages. --- python/grass/gunittest/runner.py | 2 +- python/grass/imaging/images2avi.py | 2 +- python/grass/pydispatch/dispatcher.py | 5 +++-- python/grass/pygrass/raster/abstract.py | 2 +- python/grass/pygrass/vector/geometry.py | 8 ++++---- python/grass/temporal/core.py | 2 +- python/grass/tools/session_tools.py | 16 ++++++++-------- 7 files changed, 19 insertions(+), 18 deletions(-) diff --git a/python/grass/gunittest/runner.py b/python/grass/gunittest/runner.py index 7c81d28b6c8..08b3e66ff59 100644 --- a/python/grass/gunittest/runner.py +++ b/python/grass/gunittest/runner.py @@ -59,7 +59,7 @@ def __init__( durations: int | None = None, **kwargs, ) -> None: - """Construct a TextTestResult. Subclasses should accept **kwargs + """Construct a TextTestResult. Subclasses should accept ``**kwargs`` to ensure compatibility as the interface changes.""" super().__init__( stream=stream, descriptions=descriptions, verbosity=verbosity, **kwargs diff --git a/python/grass/imaging/images2avi.py b/python/grass/imaging/images2avi.py index 3d7344a49f6..91a06bf3e13 100644 --- a/python/grass/imaging/images2avi.py +++ b/python/grass/imaging/images2avi.py @@ -89,7 +89,7 @@ def writeAvi( :param inputOptions: :param outputOptions: :param bool bg_task: if thread background task, not raise but - return error message + return error message :return str: error message """ diff --git a/python/grass/pydispatch/dispatcher.py b/python/grass/pydispatch/dispatcher.py index 1018b5e9a6c..a8fe5a99c43 100644 --- a/python/grass/pydispatch/dispatcher.py +++ b/python/grass/pydispatch/dispatcher.py @@ -4,14 +4,15 @@ providing the primary API and the core logic for the system. -Module attributes of note: +Module attributes of note:: Any -- Singleton used to signal either "Any Sender" or "Any Signal". See documentation of the _Any class. Anonymous -- Singleton used to signal "Anonymous Sender" See documentation of the _Anonymous class. -Internal attributes: +Internal attributes:: + WEAKREF_TYPES -- tuple of types/classes which represent weak references to receivers, and thus must be de- referenced on retrieval to retrieve the callable diff --git a/python/grass/pygrass/raster/abstract.py b/python/grass/pygrass/raster/abstract.py index d5db9bb3b6e..f5ad6a1d6cc 100644 --- a/python/grass/pygrass/raster/abstract.py +++ b/python/grass/pygrass/raster/abstract.py @@ -45,7 +45,7 @@ class Info: def __init__(self, name, mapset=""): - """Read the information for a raster map. :: + """Read the information for a raster map. >>> info = Info(test_raster_name) >>> info.read() diff --git a/python/grass/pygrass/vector/geometry.py b/python/grass/pygrass/vector/geometry.py index 0844e9c397a..63154984b34 100644 --- a/python/grass/pygrass/vector/geometry.py +++ b/python/grass/pygrass/vector/geometry.py @@ -1269,11 +1269,11 @@ class Node: """ def __init__(self, v_id, c_mapinfo, **kwords): - """Construct a Node object + r"""Construct a Node object - param v_id: The unique node id - param c_mapinfo: A valid pointer to the mapinfo object - param **kwords: Ignored + :param v_id: The unique node id + :param c_mapinfo: A valid pointer to the mapinfo object + :param \*\*kwords: Ignored """ self.id = v_id # vector id self.c_mapinfo = c_mapinfo diff --git a/python/grass/temporal/core.py b/python/grass/temporal/core.py index 7ab49669e98..a342393ccbd 100644 --- a/python/grass/temporal/core.py +++ b/python/grass/temporal/core.py @@ -587,7 +587,7 @@ def init( structure for raster, vector and raster3d maps as well as for the space-time dataset types strds, str3ds and stvds. - .. warning:: + .. warning:: This functions must be called before any spatio-temporal processing can be started diff --git a/python/grass/tools/session_tools.py b/python/grass/tools/session_tools.py index 61c9b1db3d2..e7b4e750cc5 100644 --- a/python/grass/tools/session_tools.py +++ b/python/grass/tools/session_tools.py @@ -446,14 +446,14 @@ def run_cmd( tool_kwargs: dict | None = None, **popen_options, ): - """Run a tool by passing its name and parameters a list of strings. + r"""Run a tool by passing its name and parameters a list of strings. The function will perform additional processing on the parameters such as importing GRASS native raster files to in-project data. :param command: list of strings to execute as the command :param input: text input for the standard input of the tool - :param **popen_options: additional options for :py:func:`subprocess.Popen` + :param \*\*popen_options: additional options for :py:func:`subprocess.Popen` """ return self._run_cmd(command, input=input, **popen_options) @@ -466,7 +466,7 @@ def _run_cmd( tool_kwargs: dict | None = None, **popen_options, ): - """Run a tool by passing its name and parameters a list of strings. + r"""Run a tool by passing its name and parameters a list of strings. If parameters were already processed using a *ParameterConverter* instance, the instance can be passed as the *parameter_converter* parameter, avoiding @@ -476,7 +476,7 @@ def _run_cmd( :param input: text input for the standard input of the tool :param parameter_converter: a Parameter converter instance if already used :param tool_kwargs: named tool arguments used for error reporting (experimental) - :param **popen_options: additional options for :py:func:`subprocess.Popen` + :param \*\*popen_options: additional options for :py:func:`subprocess.Popen` """ # Compute the environment for subprocesses and store it for later use. if "env" not in popen_options: @@ -525,7 +525,7 @@ def _run_cmd( return result def call(self, tool_name_: str, /, **kwargs): - """Run a tool by specifying its name as a string and parameters. + r"""Run a tool by specifying its name as a string and parameters. The parameters tool are tool name as a string and parameters as keyword arguments. The keyword arguments may include an argument *flags* which is a @@ -536,13 +536,13 @@ def call(self, tool_name_: str, /, **kwargs): strings for execution. :param tool_name_: name of a GRASS tool - :param **kwargs: tool parameters + :param \*\*kwargs: tool parameters """ args, popen_options = gs.popen_args_command(tool_name_, **kwargs) return self.call_cmd(args, **popen_options) def call_cmd(self, command, tool_kwargs=None, input=None, **popen_options): - """Run a tool by passing its name and parameters as a list of strings. + r"""Run a tool by passing its name and parameters as a list of strings. The function is similar to :py:func:`subprocess.run` but with different defaults and return value. @@ -550,7 +550,7 @@ def call_cmd(self, command, tool_kwargs=None, input=None, **popen_options): :param command: list of strings to execute as the command :param tool_kwargs: named tool arguments used for error reporting :param input: text input for the standard input of the tool - :param **popen_options: additional options for :py:func:`subprocess.Popen` + :param \*\*popen_options: additional options for :py:func:`subprocess.Popen` """ # We allow the user to overwrite env, which allows for maximum flexibility # with some potential for confusion when the user uses a broken environment.