From: John Snow Date: Tue, 11 Mar 2025 03:42:50 +0000 (-0400) Subject: docs/qapidoc: add visit_sections() method X-Git-Tag: v10.0.0-rc0~11^2~12 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8cb0a41490364400bc6b1c361b8e1abf9c21bd76;p=thirdparty%2Fqemu.git docs/qapidoc: add visit_sections() method Implement the actual main dispatch method that processes and handles the list of doc sections for a given QAPI entity. Process doc sections in strict source order. This is good; reordering doc text is undesirable. Improvement over the old doc generator, which can reorder doc comments that don't adhere to (largely unspoken) conventions. Signed-off-by: John Snow Message-ID: <20250311034303.75779-53-jsnow@redhat.com> Acked-by: Markus Armbruster [Commit message extended] Signed-off-by: Markus Armbruster --- diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index a8e19487d0..83022b15ca 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -288,6 +288,31 @@ class Transmogrifier: self.ensure_blank_line() + def visit_sections(self, ent: QAPISchemaDefinition) -> None: + sections = ent.doc.all_sections if ent.doc else [] + + # Add sections in source order: + for section in sections: + if section.kind == QAPIDoc.Kind.PLAIN: + self.visit_paragraph(section) + elif section.kind == QAPIDoc.Kind.MEMBER: + assert isinstance(section, QAPIDoc.ArgSection) + self.visit_member(section) + elif section.kind == QAPIDoc.Kind.FEATURE: + assert isinstance(section, QAPIDoc.ArgSection) + self.visit_feature(section) + elif section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO): + # Since is handled in preamble, TODO is skipped intentionally. + pass + elif section.kind == QAPIDoc.Kind.RETURNS: + self.visit_returns(section) + elif section.kind == QAPIDoc.Kind.ERRORS: + self.visit_errors(section) + else: + assert False + + self.ensure_blank_line() + # Transmogrification core methods def visit_module(self, path: str) -> None: