Re: [PATCH v3 07/16] qapi/docs: add "Intro" section

On Tue, Jun 9, 2026 at 6:59 AM Markus Armbruster <[email protected]> wrote:
>
> John Snow <[email protected]> writes:
>
> > This patch adds an "Intro" doc section, intended to eventually replace
> > the "Plain" doc section alongside a forthcoming "Details" section.
> >
> > For now, this section is not actually instantiated or used, but
> > subsequent patches will slowly convert the leading introductory sections
> > of QAPIDoc documentation to use this new section.
> >
> > A main motivation of this series of changes is to more explicitly
> > delineate the "Introductory" documentation for each QAPI definition for
> > the sake of the inliner. When inlining members, examples, and details
> > from multiple QAPIDoc sections, we will want to omit the "Introductory"
> > text from inlined definitions while keeping notes, caution boxes,
> > examples, and so on. This new section facilitates that.
> >
> > Signed-off-by: John Snow <[email protected]>
> > ---
> >  docs/sphinx/qapidoc.py | 2 +-
> >  scripts/qapi/parser.py | 3 ++-
> >  2 files changed, 3 insertions(+), 2 deletions(-)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index c2f09bac16c..1f7c15b7075 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
> >          for i, section in enumerate(sections):
> >              section.text = self.reformat_arobase(section.text)
> >
> > -            if section.kind == QAPIDoc.Kind.PLAIN:
> > +            if section.kind.name in ("PLAIN", "INTRO"):
>
> Is the change from QAPIDoc.Kind.FOO to "FOO" just for brevity, or is
> something going on I don't understand?

Just brevity, honestly. I'm using the .name attribute and checking
against strings. Otherwise it didn't fit on a single line.
Inconsistent style, but I guess I chose what I disliked least.

>
> >                  self.visit_paragraph(section)
> >              elif section.kind == QAPIDoc.Kind.MEMBER:
> >                  assert isinstance(section, QAPIDoc.ArgSection)
> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> > index d8068bb1bf6..97e7dacb0fd 100644
> > --- a/scripts/qapi/parser.py
> > +++ b/scripts/qapi/parser.py
> > @@ -681,6 +681,7 @@ class Kind(enum.Enum):
> >          ERRORS = 4
> >          SINCE = 5
> >          TODO = 6
> > +        INTRO = 7
> >
> >          @staticmethod
> >          def from_string(kind: str) -> 'QAPIDoc.Kind':
> > @@ -748,7 +749,7 @@ def has_features(self) -> bool:
> >      def end(self) -> None:
> >          for section in self.all_sections:
> >              section.text = section.text.strip('\n')
> > -            if section.kind != QAPIDoc.Kind.PLAIN and section.text == '':
> > +            if not (section.kind.name in ("INTRO", "PLAIN") or section.text):
> >                  raise QAPISemError(
> >                      section.info, "text required after '%s:'" % section.kind)
>