Daniel P. Berrangé <berra...@redhat.com> writes: > On Fri, Feb 16, 2024 at 03:58:35PM +0100, Markus Armbruster wrote: >> Putting a blank line before section tags and 'Features:' is good, >> existing practice. Enforce it. >> >> Signed-off-by: Markus Armbruster <arm...@redhat.com> >> --- >> docs/devel/qapi-code-gen.rst | 15 +++++++++------ >> scripts/qapi/parser.py | 11 ++++++++--- >> tests/qapi-schema/doc-duplicated-return.err | 2 +- >> tests/qapi-schema/doc-duplicated-return.json | 1 + >> tests/qapi-schema/doc-duplicated-since.err | 2 +- >> tests/qapi-schema/doc-duplicated-since.json | 1 + >> tests/qapi-schema/doc-good.json | 9 +++++++++ >> tests/qapi-schema/doc-invalid-return.err | 2 +- >> tests/qapi-schema/doc-invalid-return.json | 1 + >> 9 files changed, 32 insertions(+), 12 deletions(-) > > Reviewed-by: Daniel P. Berrangé <berra...@redhat.com> > > >> @@ -574,9 +577,11 @@ def end_comment(self) -> None: >> def _match_at_name_colon(string: str) -> Optional[Match[str]]: >> return re.match(r'@([^:]*): *', string) >> >> - @staticmethod >> - def _match_section_tag(string: str) -> Optional[Match[str]]: >> - return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string) >> + def _match_section_tag(self, string: str) -> Optional[Match[str]]: >> + if not self._first_line_in_paragraph: >> + return None >> + return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', >> + string) > > I guess I have a minor worry that we're silently ignoring > these tags when there's no blank line. Could result in > docs silently rendering in the wrong way if (when) someone > forgets the blank line.
True. We could make it an error. Can flag occurences in the middle of a free-form paragraph that happen to be at the beginning of a line, but that seems unlikely. Of course, rST is full of similar syntactic traps anyway. To quote Paolo, "I find it to be the Perl of ASCII-based markups."
