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 <js...@redhat.com>
---
docs/sphinx/qapidoc.py | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 604ab109a19..cc7d9c1df9c 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -451,6 +451,12 @@ def visit_entity(self, ent: QAPISchemaDefinition) -> None:
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 @@ def transmogrify(self, schema: QAPISchema) ->
nodes.Element:
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.48.1
