motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 04:13:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/qapidoc: add transmogrifier stub

Browse source 
This commit adds a stubbed option to the qapi-doc directive that opts-in
to the new rST generator; the implementation of which will follow in
subsequent commits.

Once all QAPI documents have been converted, this option and the old
qapidoc implementation can be dropped.

Note that moving code outside of the try...except block has no impact
because the code moved outside of that block does not ever raise a
QAPIError.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-36-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-03-10 23:42:33 -04:00 • committed by Markus Armbruster
parent d7ca9a3a4c
commit 7d125c339d
1 changed files with 28 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/sphinx/qapidoc.py
View file

@ -452,9 +452,9 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line)
self._sphinx_directive.do_parse(rstlist, node)
def get_document_nodes(self):
"""Return the list of docutils nodes which make up the document"""
return self._top_node.children
def get_document_node(self):
"""Return the root docutils node which makes up the document"""
return self._top_node
# Turn the black formatter on for the rest of the file.
@ -503,7 +503,10 @@ class QAPIDocDirective(NestedDirective):
required_argument = 1
optional_arguments = 1
option_spec = {"qapifile": directives.unchanged_required}
option_spec = {
"qapifile": directives.unchanged_required,
"transmogrify": directives.flag,
}
has_content = False
def new_serialno(self):
@ -511,10 +514,24 @@ class QAPIDocDirective(NestedDirective):
env = self.state.document.settings.env
return "qapidoc-%d" % env.new_serialno("qapidoc")
def transmogrify(self, schema) -> nodes.Element:
raise NotImplementedError
def legacy(self, schema) -> nodes.Element:
vis = QAPISchemaGenRSTVisitor(self)
vis.visit_begin(schema)
for doc in schema.docs:
if doc.symbol:
vis.symbol(doc, schema.lookup_entity(doc.symbol))
else:
vis.freeform(doc)
return vis.get_document_node()
def run(self):
env = self.state.document.settings.env
qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
qapidir = os.path.dirname(qapifile)
transmogrify = "transmogrify" in self.options
try:
schema = QAPISchema(qapifile)
@ -522,20 +539,18 @@ class QAPIDocDirective(NestedDirective):
# First tell Sphinx about all the schema files that the
# output documentation depends on (including 'qapifile' itself)
schema.visit(QAPISchemaGenDepVisitor(env, qapidir))
vis = QAPISchemaGenRSTVisitor(self)
vis.visit_begin(schema)
for doc in schema.docs:
if doc.symbol:
vis.symbol(doc, schema.lookup_entity(doc.symbol))
else:
vis.freeform(doc)
return vis.get_document_nodes()
except QAPIError as err:
# Launder QAPI parse errors into Sphinx extension errors
# so they are displayed nicely to the user
raise ExtensionError(str(err)) from err
if transmogrify:
contentnode = self.transmogrify(schema)
else:
contentnode = self.legacy(schema)
return contentnode.children
class QMPExample(CodeBlock, NestedDirective):
"""