[1/7] qapi: make since sections special WIP

Commit Message

Markus Armbruster May 6, 2024, 11:02 a.m. UTC

since moves to end in generated output
---
 docs/sphinx/qapidoc.py         | 22 +++++++++++++++++-----
 scripts/qapi/parser.py         |  5 +++--
 tests/qapi-schema/test-qapi.py |  2 ++
 3 files changed, 22 insertions(+), 7 deletions(-)

Comments

Philippe Mathieu-Daudé May 6, 2024, 11:44 a.m. UTC | #1

On 6/5/24 13:02, Markus Armbruster wrote:
> since moves to end in generated output
> ---
>   docs/sphinx/qapidoc.py         | 22 +++++++++++++++++-----
>   scripts/qapi/parser.py         |  5 +++--
>   tests/qapi-schema/test-qapi.py |  2 ++
>   3 files changed, 22 insertions(+), 7 deletions(-)

Alternatively use git-publish to send pull requests :)

$ git publish --pull-request --sign-pull

https://github.com/stefanha/git-publish/blob/master/git-publish.pod

Markus Armbruster May 6, 2024, 12:45 p.m. UTC | #2

Markus Armbruster <[e-mail]> writes:

> since moves to end in generated output

Sent by accident, please ignore.

Markus Armbruster May 6, 2024, 12:48 p.m. UTC | #3

Philippe Mathieu-Daudé <[e-mail]> writes:

> On 6/5/24 13:02, Markus Armbruster wrote:
>> since moves to end in generated output
>> ---
>>   docs/sphinx/qapidoc.py         | 22 +++++++++++++++++-----
>>   scripts/qapi/parser.py         |  5 +++--
>>   tests/qapi-schema/test-qapi.py |  2 ++
>>   3 files changed, 22 insertions(+), 7 deletions(-)
>
> Alternatively use git-publish to send pull requests :)

Touché; I'm a troglodyte ;)

> $ git publish --pull-request --sign-pull
>
> https://github.com/stefanha/git-publish/blob/master/git-publish.pod

Patch

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8d428c64b0..ac81003f0e 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -250,6 +250,13 @@  def _nodes_for_features(self, doc):
         section += dlnode
         return [section]
 
+    def _nodes_for_since(self, doc):
+        if doc.since:
+            section = self._make_section('Since')
+            self._parse_text_into_node(doc.since.text, section)
+            return [section]
+        return []
+
     def _nodes_for_example(self, exampletext):
         """Return list of doctree nodes for a code example snippet"""
         return [nodes.literal_block(exampletext, exampletext)]
@@ -305,7 +312,8 @@  def visit_enum_type(self, name, info, ifcond, features, members, prefix):
                       self._nodes_for_enum_values(doc)
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
-                      + self._nodes_for_if_section(ifcond))
+                      + self._nodes_for_if_section(ifcond)
+                      + self._nodes_for_since(doc))
 
     def visit_object_type(self, name, info, ifcond, features,
                           base, members, variants):
@@ -316,7 +324,8 @@  def visit_object_type(self, name, info, ifcond, features,
                       self._nodes_for_members(doc, 'Members', base, variants)
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
-                      + self._nodes_for_if_section(ifcond))
+                      + self._nodes_for_if_section(ifcond)
+                      + self._nodes_for_since(doc))
 
     def visit_alternate_type(self, name, info, ifcond, features, variants):
         doc = self._cur_doc
@@ -324,7 +333,8 @@  def visit_alternate_type(self, name, info, ifcond, features, variants):
                       self._nodes_for_members(doc, 'Members')
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
-                      + self._nodes_for_if_section(ifcond))
+                      + self._nodes_for_if_section(ifcond)
+                      + self._nodes_for_since(doc))
 
     def visit_command(self, name, info, ifcond, features, arg_type,
                       ret_type, gen, success_response, boxed, allow_oob,
@@ -335,7 +345,8 @@  def visit_command(self, name, info, ifcond, features, arg_type,
                                                 arg_type if boxed else None)
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
-                      + self._nodes_for_if_section(ifcond))
+                      + self._nodes_for_if_section(ifcond)
+                      + self._nodes_for_since(doc))
 
     def visit_event(self, name, info, ifcond, features, arg_type, boxed):
         doc = self._cur_doc
@@ -344,7 +355,8 @@  def visit_event(self, name, info, ifcond, features, arg_type, boxed):
                                                 arg_type if boxed else None)
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
-                      + self._nodes_for_if_section(ifcond))
+                      + self._nodes_for_if_section(ifcond)
+                      + self._nodes_for_since(doc))
 
     def symbol(self, doc, entity):
         """Add documentation for one symbol to the document tree
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 7b13a583ac..0237d13da9 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -646,7 +646,7 @@  def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):
         self.errors: Optional[QAPIDoc.Section] = None
         # "Since" section
         self.since: Optional[QAPIDoc.Section] = None
-        # sections other than .body, .args, .features
+        # sections other than .body, .args, .features, .since
         self.sections: List[QAPIDoc.Section] = []
 
     def end(self) -> None:
@@ -683,7 +683,8 @@  def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None:
                 raise QAPISemError(
                     info, "duplicated '%s' section" % tag)
             self.since = section
-        self.sections.append(section)
+        if tag != 'Since':
+            self.sections.append(section)
         self.all_sections.append(section)
 
     def _new_description(self, info: QAPISourceInfo, name: str,
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 40095431ae..642daa29a4 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -131,6 +131,8 @@  def test_frontend(fname):
             print('    feature=%s\n%s' % (feat, section.text))
         for section in doc.sections:
             print('    section=%s\n%s' % (section.tag, section.text))
+        if doc.since:
+            print('    section=%s\n%s' % (doc.since.tag, doc.since.text))
 
 
 def open_test_result(dir_name, file_name, update):