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)
>
