From b1df602ebbd06d56311a77d195284216263b13f8 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:07 -0400 Subject: [PATCH] docs/qapidoc: add :namespace: option to qapi-doc directive Add a :namespace: option to the qapi-doc directive, which inserts a qapi:namespace directive into the start of the generated document. This, in turn, associates all auto-generated definitions by this directive with the specified namespace. The source info for these generated lines are credited to the start of the qapi-doc directive, which isn't precisely correct, but I wasn't sure how to get it more accurate without some re-parsing shenanigans. Signed-off-by: John Snow Message-ID: <20250313044312.189276-7-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 432fef04b0..661b2c4ed0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -451,6 +451,12 @@ class Transmogrifier: finally: self._curr_ent = None + def set_namespace(self, namespace: str, source: str, lineno: int) -> None: + self.add_line_raw( + f".. qapi:namespace:: {namespace}", source, lineno + 1 + ) + self.ensure_blank_line() + class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module @@ -496,6 +502,7 @@ class QAPIDocDirective(NestedDirective): optional_arguments = 1 option_spec = { "qapifile": directives.unchanged_required, + "namespace": directives.unchanged, "transmogrify": directives.flag, } has_content = False @@ -510,6 +517,11 @@ class QAPIDocDirective(NestedDirective): vis = Transmogrifier() modules = set() + if "namespace" in self.options: + vis.set_namespace( + self.options["namespace"], *self.get_source_info() + ) + for doc in schema.docs: module_source = doc.info.fname if module_source not in modules: -- 2.39.5