docs: Fix reStructuredText markup in Python docstrings - #7741
Merged
Conversation
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.
echoix
approved these changes
Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This fixes markup issues in the Python docstrings consumed by Sphinx. Follow-up to #7526.
Details
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.literal blocks, so that their plain-text layout is preserved instead
of being misparsed as definition lists and block quotes.
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.
Node constructor into an actual field list.
grass.tools.session_tools: escape or quote the asterisks so that
"**kwargs" is not parsed as the start of inline strong markup.
field body, so that the field list is not cut short.
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.