From: John Snow <js...@redhat.com>
The double-colon synax is rST formatting that precedes a literal code
block. We do not want to capture these as QAPI-specific sections.
Coerce blocks that start with e.g. "Example::" to be parsed as untagged
paragraphs instead of special tagged sections.
Signed-off-by: John Snow <js...@redhat.com>
Message-ID: <20240626222128.406106-14-js...@redhat.com>
Reviewed-by: Markus Armbruster <arm...@redhat.com>
[Indentation tweaked for consistency]
Signed-off-by: Markus Armbruster <arm...@redhat.com>
---
scripts/qapi/parser.py | 9 +++++++--
tests/qapi-schema/doc-good.json | 3 +++
tests/qapi-schema/doc-good.out | 3 +++
tests/qapi-schema/doc-good.txt | 3 +++
4 files changed, 16 insertions(+), 2 deletions(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 0a13f0f541..6ad5663e54 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -544,10 +544,15 @@ def get_doc(self) -> 'QAPIDoc':
line = self.get_doc_indented(doc)
no_more_args = True
elif match := re.match(
- r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
- line):
+ r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
+ r'(?!::): *',
+ line,
+ ):
# tagged section
+ # Note: "sections" with two colons are left alone as
+ # rST markup and not interpreted as a section heading.
+
# TODO: Remove this error sometime in 2025 or so
# after we've fully transitioned to the new qapidoc
# generator.
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 32ff910b4f..b565895858 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -181,6 +181,9 @@
# - *verbatim*
# - {braces}
#
+# Note::
+# Ceci n'est pas une note
+#
# Since: 2.10
##
{ 'command': 'cmd',
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 631dc9f8da..a8e9456f60 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -190,6 +190,9 @@ frobnicate
section=Examples
- *verbatim*
- {braces}
+ section=None
+Note::
+ Ceci n'est pas une note
section=Since
2.10
doc symbol=cmd-boxed
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index d8bfa742c2..30d457e548 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -231,6 +231,9 @@ Examples
- *verbatim*
- {braces}
+Note::
+ Ceci n'est pas une note
+
Since
~~~~~
--
2.45.0
