This patch begins distinguishing "Plain" sections as being either
"Intro" or "Details" sections for the purpose of knowing when and where
to inline those sections.
Signed-off-by: John Snow <js...@redhat.com>
---
docs/sphinx/qapidoc.py | 4 ++--
scripts/qapi/parser.py | 30 +++++++++++++++++++-----------
tests/qapi-schema/doc-good.out | 8 ++++----
3 files changed, 25 insertions(+), 17 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 2d83556629d..154ebc1b4cd 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -289,7 +289,7 @@ def visit_sections(self, ent: QAPISchemaEntity) -> None:
# Add sections *in the order they are documented*:
for section in sections:
- if section.kind == QAPIDoc.Kind.PLAIN:
+ if section.kind.name in ("INTRO", "DETAIL"):
self.visit_paragraph(section)
elif section.kind == QAPIDoc.Kind.MEMBER:
self.visit_member(section)
@@ -578,7 +578,7 @@ def _nodes_for_sections(self, doc):
# Hide TODO: sections
continue
- if section.kind == QAPIDoc.Kind.PLAIN:
+ if section.kind.name in ("INTRO", "DETAIL"):
# Sphinx cannot handle sectionless titles;
# Instead, just append the results to the prior section.
container = nodes.container()
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index a8b30ae1a4b..b2f77ffdd7a 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -499,7 +499,7 @@ def get_doc(self) -> 'QAPIDoc':
doc = QAPIDoc(info, symbol)
self.accept(False)
line = self.get_doc_line()
- no_more_args = False
+ have_tagged = False
while line is not None:
# Blank lines
@@ -528,10 +528,10 @@ def get_doc(self) -> 'QAPIDoc':
if not doc.features:
raise QAPIParseError(
self, 'feature descriptions expected')
- no_more_args = True
+ have_tagged = True
elif match := self._match_at_name_colon(line):
# description
- if no_more_args:
+ if have_tagged:
raise QAPIParseError(
self,
"description of '@%s:' follows a section"
@@ -543,7 +543,7 @@ def get_doc(self) -> 'QAPIDoc':
if text:
doc.append_line(text)
line = self.get_doc_indented(doc)
- no_more_args = True
+ have_tagged = True
elif match := re.match(
r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
r'(?!::): *',
@@ -584,14 +584,20 @@ def get_doc(self) -> 'QAPIDoc':
if text:
doc.append_line(text)
line = self.get_doc_indented(doc)
- no_more_args = True
+ have_tagged = True
elif line.startswith('='):
raise QAPIParseError(
self,
"unexpected '=' markup in definition documentation")
else:
# plain paragraph(s)
- doc.ensure_untagged_section(self.info)
+ if have_tagged:
+ no_more_tags = True
+
+ # Paragraphs before tagged sections are "intro" paragraphs.
+ # Any appearing after are "detail" paragraphs.
+ intro = not have_tagged
+ doc.ensure_untagged_section(self.info, intro)
doc.append_line(line)
line = self.get_doc_paragraph(doc)
else:
@@ -640,21 +646,22 @@ class QAPIDoc:
"""
class Kind(enum.Enum):
- PLAIN = 0
+ INTRO = 0
MEMBER = 1
FEATURE = 2
RETURNS = 3
ERRORS = 4
SINCE = 5
TODO = 6
+ DETAIL = 7
@staticmethod
def from_string(kind: str) -> 'QAPIDoc.Kind':
return QAPIDoc.Kind[kind.upper()]
def text_required(self) -> bool:
- # Only "plain" sections can be empty
- return self.value not in (0,)
+ # Only Intro/Detail sections can be empty
+ return self.value not in (0, 7)
def __str__(self) -> str:
return self.name.title()
@@ -700,7 +707,7 @@ def __init__(self, info: QAPISourceInfo, symbol:
Optional[str] = None):
self.symbol: Optional[str] = symbol
# the sections in textual order
self.all_sections: List[QAPIDoc.Section] = [
- QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN)
+ QAPIDoc.Section(info, QAPIDoc.Kind.INTRO)
]
# the body section
self.body: Optional[QAPIDoc.Section] = self.all_sections[0]
@@ -725,8 +732,9 @@ def end(self) -> None:
def ensure_untagged_section(
self,
info: QAPISourceInfo,
+ intro: bool = True,
) -> None:
- kind = QAPIDoc.Kind.PLAIN
+ kind = QAPIDoc.Kind.INTRO if intro else QAPIDoc.Kind.DETAIL
if self.all_sections and self.all_sections[-1].kind == kind:
# extend current section
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 2d33a305ee7..3eb28503f6b 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -110,7 +110,7 @@ The _one_ {and only}, description on the same line
Also _one_ {and only}
feature=enum-member-feat
a member feature
- section=Plain
+ section=Detail
@two is undocumented
doc symbol=Base
body=
@@ -168,7 +168,7 @@ description starts on the same line
a feature
feature=cmd-feat2
another feature
- section=Plain
+ section=Detail
.. note:: @arg3 is undocumented
section=Returns
@Object
@@ -176,7 +176,7 @@ another feature
some
section=Todo
frobnicate
- section=Plain
+ section=Detail
.. admonition:: Notes
- Lorem ipsum dolor sit amet
@@ -209,7 +209,7 @@ If you're bored enough to read this, go see a video of
boxed cats
a feature
feature=cmd-feat2
another feature
- section=Plain
+ section=Detail
.. qmp-example::
-> "this example"
--
2.48.1
