| Message ID | 20240626222128.406106-14-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | qapi: convert "Note" and "Example" sections to rST | expand |
John Snow <jsnow@redhat.com> writes: > 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 <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com>
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 0a13f0f541a..6ad5663e545 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 32ff910b4f8..107123f8a8d 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 631dc9f8dad..bd876b6542d 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 d8bfa742c2f..30d457e5488 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 ~~~~~
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 <jsnow@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(-)