From 8d789c8cdb8de2cae39f217b6c9607ac9c036c8c Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:51 -0400 Subject: docs/sphinx: remove legacy QAPI manual generator Thanks for your service! Remove the old qapidoc and the option to enable the transmogrifier, leaving the "transmogrifier" as the ONLY qapi doc generator. This in effect also converts the QAPI test to use the new documentation generator, too. Update doc-good.txt output to match the new doc generator, which I should've done exactly when we switched over to the transmogrifier, but, uhh, oops! Notes on the new format: 1. per-member IFCOND documentation is missing. Known issue. 2. Freeform documentation without a header is now copied through into the output. This is a bug fix. Signed-off-by: John Snow Message-ID: <20250618165353.1980365-4-jsnow@redhat.com> Acked-by: Markus Armbruster Fixes: b61a4eb3f32 (docs/qapidoc: support header-less freeform sections) [Tweak commit message to say it's a bug fix, add Fixes:] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) (limited to 'docs/sphinx/qapidoc.py') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index adc14ade45..d5d2b5eeb5 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -64,8 +64,6 @@ from sphinx.util import logging from sphinx.util.docutils import SphinxDirective, switch_source_input from sphinx.util.nodes import nested_parse_with_titles -from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore - if TYPE_CHECKING: from typing import ( @@ -512,15 +510,9 @@ class QAPIDocDirective(NestedDirective): option_spec = { "qapifile": directives.unchanged_required, "namespace": directives.unchanged, - "transmogrify": directives.flag, } has_content = False - def new_serialno(self) -> str: - """Return a unique new ID string suitable for use as a node's ID""" - env = self.state.document.settings.env - return "qapidoc-%d" % env.new_serialno("qapidoc") - def transmogrify(self, schema: QAPISchema) -> nodes.Element: logger.info("Transmogrifying QAPI to rST ...") vis = Transmogrifier() @@ -598,21 +590,10 @@ class QAPIDocDirective(NestedDirective): outfile.write(f" {rcol}") outfile.write("\n") - def legacy(self, schema: QAPISchema) -> 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() # type: ignore - def run(self) -> Sequence[nodes.Node]: 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) @@ -625,11 +606,7 @@ class QAPIDocDirective(NestedDirective): # 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) - + contentnode = self.transmogrify(schema) return contentnode.children -- cgit 1.4.1