From: John Snow <jsnow@redhat.com>
Date: Tue, 11 Mar 2025 03:42:38 +0000 (-0400)
Subject: docs/qapidoc: add visit_module() method
X-Git-Tag: v10.0.0-rc0~11^2~24
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5edd7411c4f25a43400c5b8d6e5647603942f36b;p=thirdparty%2Fqemu.git

docs/qapidoc: add visit_module() method

This method annotates the start of a new module, crediting the source
location to the first line of the module file.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-41-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 c243bb6faaa..6de8c900543 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -28,6 +28,7 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 import os
+from pathlib import Path
 import sys
 from typing import TYPE_CHECKING
 
@@ -121,6 +122,14 @@ class Transmogrifier:
             # +2: correct for zero/one index, then increment by one.
             self.add_line_raw("", fname, line + 2)
 
+    # Transmogrification core methods
+
+    def visit_module(self, path: str) -> None:
+        name = Path(path).stem
+        # module directives are credited to the first line of a module file.
+        self.add_line_raw(f".. qapi:module:: {name}", path, 1)
+        self.ensure_blank_line()
+
 
 class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     """A QAPI schema visitor which adds Sphinx dependencies each module