[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 08/20] qapi/parser: differentiate intro and outro paragraphs
From: |
John Snow |
Subject: |
[PATCH 08/20] qapi/parser: differentiate intro and outro paragraphs |
Date: |
Tue, 14 May 2024 17:57:27 -0400 |
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 <jsnow@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
- Re: [PATCH 04/20] qapi/parser: preserve indentation in QAPIDoc sections, (continued)
[PATCH 01/20] [DO-NOT-MERGE]: Add some ad-hoc linting helpers., John Snow, 2024/05/14
[PATCH 06/20] qapi/parser: fix comment parsing immediately following a doc block, John Snow, 2024/05/14
[PATCH 07/20] qapi/parser: add semantic 'kind' parameter to QAPIDoc.Section, John Snow, 2024/05/14
[PATCH 10/20] qapi/schema: add __iter__ method to QAPISchemaVariants, John Snow, 2024/05/14
[PATCH 08/20] qapi/parser: differentiate intro and outro paragraphs,
John Snow <=
[PATCH 09/20] qapi/parser: add undocumented stub members to all_sections, John Snow, 2024/05/14
[PATCH 13/20] docs/qapidoc: fix nested parsing under untagged sections, John Snow, 2024/05/14
[PATCH 05/20] qapi/parser: adjust info location for doc body section, John Snow, 2024/05/14
[PATCH 11/20] qapi/schema: add doc_visible property to QAPISchemaDefinition, John Snow, 2024/05/14