Skip to content

docs: Fix reStructuredText markup in Python docstrings - #7741

Merged
echoix merged 1 commit into
OSGeo:mainfrom
wenzeslaus:sphinx-docstring-markup-fixes
Jul 17, 2026
Merged

docs: Fix reStructuredText markup in Python docstrings#7741
echoix merged 1 commit into
OSGeo:mainfrom
wenzeslaus:sphinx-docstring-markup-fixes

Conversation

@wenzeslaus

Copy link
Copy Markdown
Member

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.
  • 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.

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.
@wenzeslaus wenzeslaus added this to the 8.6.0 milestone Jul 17, 2026
@github-actions github-actions Bot added Python Related code is in Python libraries labels Jul 17, 2026
@echoix
echoix merged commit 7b77106 into OSGeo:main Jul 17, 2026
26 checks passed
@wenzeslaus
wenzeslaus deleted the sphinx-docstring-markup-fixes branch July 17, 2026 21:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

libraries Python Related code is in Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants