Add a semantic tag to paragraphs that appear *before* tagged sections/members/features and those that appear after. This will control how they are inlined when doc sections are merged and flattened.
Signed-off-by: John Snow <js...@redhat.com> --- scripts/qapi/parser.py | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index cf4cbca1c1f..b1794f71e12 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -503,6 +503,10 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line = self.get_doc_line() no_more_args = False + # Paragraphs before members/features/tagged are "intro" paragraphs. + # Any appearing subsequently are "outro" paragraphs. + # This is only semantic metadata for the doc generator. + intro = True while line is not None: # Blank lines @@ -532,6 +536,7 @@ def get_doc(self) -> 'QAPIDoc': raise QAPIParseError( self, 'feature descriptions expected') no_more_args = True + intro = False elif match := self._match_at_name_colon(line): # description if no_more_args: @@ -547,6 +552,7 @@ def get_doc(self) -> 'QAPIDoc': doc.append_line(text) line = self.get_doc_indented(doc) no_more_args = True + intro = False elif match := re.match( r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): @@ -557,13 +563,14 @@ def get_doc(self) -> 'QAPIDoc': doc.append_line(text) line = self.get_doc_indented(doc) no_more_args = True + intro = False elif line.startswith('='): raise QAPIParseError( self, "unexpected '=' markup in definition documentation") else: # tag-less paragraph - doc.ensure_untagged_section(self.info) + doc.ensure_untagged_section(self.info, intro) doc.append_line(line) line = self.get_doc_paragraph(doc) else: @@ -617,7 +624,7 @@ def __init__( self, info: QAPISourceInfo, tag: Optional[str] = None, - kind: str = 'paragraph', + kind: str = 'intro-paragraph', ): # section source info, i.e. where it begins self.info = info @@ -625,7 +632,7 @@ def __init__( self.tag = tag # section text without tag self.text = '' - # section type - {paragraph, feature, member, tagged} + # section type - {<intro|outro>-paragraph, feature, member, tagged} self.kind = kind def append_line(self, line: str) -> None: @@ -666,7 +673,11 @@ def end(self) -> None: raise QAPISemError( section.info, "text required after '%s:'" % section.tag) - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: + def ensure_untagged_section( + self, + info: QAPISourceInfo, + intro: bool = True, + ) -> None: if self.all_sections and not self.all_sections[-1].tag: section = self.all_sections[-1] # Section is empty so far; update info to start *here*. @@ -677,7 +688,8 @@ def ensure_untagged_section(self, info: QAPISourceInfo) -> None: self.all_sections[-1].text += '\n' return # start new section - section = self.Section(info) + kind = ("intro" if intro else "outro") + "-paragraph" + section = self.Section(info, kind=kind) self.sections.append(section) self.all_sections.append(section) -- 2.44.0