From: John Snow <jsnow@redhat.com>
Date: Tue, 11 Mar 2025 03:42:45 +0000 (-0400)
Subject: docs/qapidoc: add add_field() and generate_field() helper methods
X-Git-Tag: v10.0.0-rc0~11^2~17
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=604df9bb001fc66f77d349ce63e870af84b42d96;p=thirdparty%2Fqemu.git

docs/qapidoc: add add_field() and generate_field() helper methods

These are simple rST generation methods that assist in getting the types
and formatting correct for a field list entry. add_field() is a more
raw, direct call while generate_field() is intended to be used for
generating the correct field from a member object.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-48-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 5144bb965a..2f85fe0bc3 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -136,6 +136,20 @@ class Transmogrifier:
             # +2: correct for zero/one index, then increment by one.
             self.add_line_raw("", fname, line + 2)
 
+    def add_field(
+        self,
+        kind: str,
+        name: str,
+        body: str,
+        info: QAPISourceInfo,
+        typ: Optional[str] = None,
+    ) -> None:
+        if typ:
+            text = f":{kind} {typ} {name}: {body}"
+        else:
+            text = f":{kind} {name}: {body}"
+        self.add_lines(text, info)
+
     def format_type(
         self, ent: Union[QAPISchemaDefinition | QAPISchemaMember]
     ) -> Optional[str]:
@@ -160,6 +174,16 @@ class Transmogrifier:
 
         return ret
 
+    def generate_field(
+        self,
+        kind: str,
+        member: QAPISchemaMember,
+        body: str,
+        info: QAPISourceInfo,
+    ) -> None:
+        typ = self.format_type(member)
+        self.add_field(kind, member.name, body, info, typ)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None: