Re: [PATCH 2/9] qapi: convert intro sections for unit tests

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 22, 2026 at 1:06 PM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  tests/qapi-schema/doc-good.json                | 10 +++++-----
>> >  tests/qapi-schema/doc-good.out                 | 13 +++++--------
>> >  tests/qapi-schema/doc-interleaved-section.err  |  2 +-
>> >  tests/qapi-schema/doc-interleaved-section.json |  3 +--
>> >  4 files changed, 12 insertions(+), 16 deletions(-)
>> >
>> > diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
>> > index fac13425b72..00721d5c522 100644
>> > --- a/tests/qapi-schema/doc-good.json
>> > +++ b/tests/qapi-schema/doc-good.json
>> > @@ -94,12 +94,11 @@
>> >
>> >  ##
>> >  # @Variant1:
>> > +#     A paragraph
>> >  #
>> > -# A paragraph
>> > +#     Another paragraph
>> >  #
>> > -# Another paragraph
>> > -#
>> > -# @var1 is undocumented
>> > +#     @var1 is undocumented
>>
>> Let's keep '@var1 is undocumented' plain.  That way, it stays close to
>> "author forgot the colon after the member name", which I find useful.
>
> OK, but it will very soon be disallowed in that position; it will have
> to be moved below Features et al, eventually. Making this change, but
> heads up that it necessitates another patch in the order enforcement
> series.

Yes.

>> >  #
>> >  # Features:
>> >  # @variant1-feat: a feature
>> > @@ -206,7 +205,8 @@
>> >
>> >  ##
>> >  # @cmd-boxed:
>> > -# If you're bored enough to read this, go see a video of boxed cats
>> > +#     If you're bored enough to read this, go see a video of boxed
>> > +#     cats
>> >  #
>> >  # Features:
>> >  # @cmd-feat1: a feature
>> > diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
>> > index 371dd25ffc7..8c0818a3f0d 100644
>> > --- a/tests/qapi-schema/doc-good.out
>> > +++ b/tests/qapi-schema/doc-good.out
>> > @@ -126,13 +126,11 @@ doc symbol=Base
>> >   minimally indented
>> >  doc symbol=Variant1
>> >      Intro
>> > +    A paragraph
>> >
>> > -    Plain
>> > -A paragraph
>> > +    Another paragraph
>> >
>> > -Another paragraph
>> > -
>> > -@var1 is undocumented
>> > +    @var1 is undocumented
>> >      Member=var1
>> >
>> >      Feature=variant1-feat
>> > @@ -213,9 +211,8 @@ Note::
>> >  2.10
>> >  doc symbol=cmd-boxed
>> >      Intro
>> > -
>> > -    Plain
>> > -If you're bored enough to read this, go see a video of boxed cats
>> > +    If you're bored enough to read this, go see a video of boxed
>> > +    cats
>> >      Feature=cmd-feat1
>> >  a feature
>> >      Feature=cmd-feat2
>>
>> I'm mildly surprised that the intro's indentation isn't stripped.  Maybe
>> we discussed that already, and I forgot.  Anyway, it works, and changing
>> it is way out of scope right now.
>
> *searching resident databanks*
>
> I think I was striving for minimal processing of the text prior to
> handoff to sphinx for reasons of preserving accurate source
> information.
>
> qapidoc.py has this code:
> ```
>     def visit_plaintext(self, section: QAPIDoc.Section) -> None:
>         # Squelch empty paragraphs.
>         if not section.text:
>             return
>
>         # Intro sections, which are indented in QAPI source, need to
>         # be dedented to avoid accidental block quotes in ReST syntax.
>         dedent = bool(section.kind == QAPIDoc.Kind.INTRO)
>         self.ensure_blank_line()
>         self.add_lines(section.text, section.info, dedent)
>         self.ensure_blank_line()
> ```
>
> As a result, the unit test plaintext versions retain that indentation.
> This actually matches how we treat indentation for member text, which
> is also preserved and represented in the plaintext test output!
>
> Granted, now that I have excised the backwards compatibility demon
> from qapidoc, it is possible we can conduct another audit on source
> information preservation and some things might be able to be
> simplified, but I think this is fine and good for now.

Maybe, eventually.  You got far more interesting work piled up that I
want to merge.

[...]