On 30.10.25 17:01, Markus Armbruster wrote:
Vladimir Sementsov-Ogievskiy <[email protected]> writes:
Add explicit validation for QAPI documentation formatting rules:
1. Lines must not exceed 70 columns in width (including '# ' prefix)
2. Sentences must be separated by two spaces
Example sections are excluded, we don't require them to be <= 70,
that would be too restrictive.
Example sections share common 80-columns recommendations (not
requirements).
Signed-off-by: Vladimir Sementsov-Ogievskiy <[email protected]>
---
Hi all!
This substitutes my previous attempt
"[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences"
Supersedes: <[email protected]>
v3:
01: ignore example sections
other commits: dropped :)
Of course, this _does not_ build on top of current master. v3 is
to be based on top of coming soon doc-cleanup series by Markus.
I'll post this today.
scripts/qapi/parser.py | 46 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 45 insertions(+), 1 deletion(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 9fbf80a541..b9d76fff39 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
[..]
single_space_pattern = r'(\be\.g\.|^ *\d\.|([.!?])) [A-Z0-9(]'
for m in list(re.finditer(single_space_pattern, line)):
if not m.group(2):
continue
This uses a common regexp trick: match exception | ... | (wanted), then
check whether the group containing wanted matched.
Cool, I didn't know this!
+ raise QAPIParseError(
+ self, f"documentation has single space after sentence "
+ f"ending. Use two spaces between sentences: "
+ f"...{line[m.start()-5:m.end()+5]}..."
[..]
I can offer a disgusting hack:
# HACK so the error message points to the the offending spot
self.pos = self.line_pos + 2 + m.start(2) + 1
raise QAPIParseError(
self, "Use two spaces between sentences")
This results in
../qapi/block-core.json:162:47: Use two spaces between sentences
Emacs then takes me right to the offending single space.
Great!
+ )
@staticmethod
def _match_at_name_colon(string: str) -> Optional[Match[str]]:
Thanks for careful review, will resend soon.
--
Best regards,
Vladimir
