@samitouri / QOSamiQemu / commits / b996c767a3

qapi: new doc comment "Intro" section

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 <jsnow@redhat.com> Message-ID: <20260611042332.482979-8-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>

John Snow committed Jun 11, 2026 at 00:23 UTC b996c767a33bb24edd392843e844493aa279b16b

2 files changed +3 -2

docs/sphinx/qapidoc.py

+1 -1

@@ -368,7 +368,7 @@ class Transmogrifier:

368 for i, section in enumerate(sections):

369 section.text = self.reformat_arobase(section.text)

370

371 - if section.kind == QAPIDoc.Kind.PLAIN:

371 + if section.kind.name in ("PLAIN", "INTRO"):

372 self.visit_paragraph(section)

373 elif section.kind == QAPIDoc.Kind.MEMBER:

374 assert isinstance(section, QAPIDoc.ArgSection)

scripts/qapi/parser.py

+2 -1

@@ -681,6 +681,7 @@ class QAPIDoc:

681 ERRORS = 4

682 SINCE = 5

683 TODO = 6

684 + INTRO = 7

685

686 @staticmethod

687 def from_string(kind: str) -> 'QAPIDoc.Kind':

@@ -748,7 +749,7 @@ class QAPIDoc:

749 def end(self) -> None:

750 for section in self.all_sections:

751 section.text = section.text.strip('\n')

751 - if section.kind != QAPIDoc.Kind.PLAIN and section.text == '':

752 + if not (section.kind.name in ("INTRO", "PLAIN") or section.text):

753 raise QAPISemError(

754 section.info, "text required after '%s:'" % section.kind)

755