On Tue, Feb 20, 2024 at 05:06:42PM +0100, Markus Armbruster wrote: > 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."
Yes, probably not worth the hassle. With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
