Skip to content

fix: preserve custom reST field markers and link-body spacing - #396

Merged
weibullguy merged 3 commits into
PyCQA:masterfrom
jihtsan:codex/279-custom-rst-fields
Oct 22, 2026
Merged

weibullguy merged 3 commits into
PyCQA:masterfrom
jihtsan:codex/279-custom-rst-fields

Conversation

@jihtsan

@jihtsan jihtsan commented Oct 18, 2026

Copy link
Copy Markdown
Contributor

Fixes #279.

Custom reStructuredText fields such as :calls: are not in the Sphinx field-name list, so wrapping can move their continuation lines to the field's own indentation and break the field/link structure.

Recognize extensible reST field markers at the start of a line, using the field-marker grammar rather than adding a calls exception. Keep the existing permissive Sphinx recognition for compatibility. Use only the marker span when wrapping, and keep a separating space before inline-link bodies as required by reST. Update the corresponding requirements-table entry; empty bodies still receive no trailing space.

Leave the existing list/code classifier unchanged so custom fields with complex bodies retain their previous protection. Add 24 cases covering custom/typed/Unicode/escaped-colon markers, prose and roles, long-link continuation indentation and idempotence, and module-level bullet/enumerated/doctest bodies.

Validation on macOS arm64:

  • Against unchanged base: 12 new cases fail; 12 controls pass. With the fix all pass.
  • Python 3.10.21: full suite 664 passed, 4 skipped.
  • Python 3.14.6: full suite 665 passed, 3 skipped.
  • Real CLI plus Docutils: original Issue function docstring retains all three fields and the exact URI, without warnings. Ten independent CLI/Docutils comparisons preserve complex field-body structures, fields, URIs and idempotence.
  • Black 26.3.1, Ruff, isort, mypy, pydocstyle, source docformatter check and git diff check pass for the changed files/source as applicable.

Sphinx 6.2.1 (locked version) generates HTML on both base and branch, but strict -W builds both fail on the existing missing _static directory warning. That unrelated configuration is unchanged. Linux, Windows and other Python versions were not run locally. --force-wrap retains its documented flattening behavior. An independent module-level long-URI case has the same existing limitation on base and branch; this patch does not claim to repair that separate path.

@weibullguy
weibullguy merged commit 16cecc8 into PyCQA:master Oct 22, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docformatter seems to have trouble with linebreaks inside directives in info fields

2 participants