From nobody Sun Apr 6 23:17:10 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1736881421; cv=none; d=zohomail.com; s=zohoarc; b=HoPzBO9nRGUwK47tdrDUksLi5HFR9l5TqvRVsUVeMGItOIX+dybuTYN073GZCJFO+vKU6x8rxuoxybNIrebMqETUKMom/EbjTip6V3yYfdMwgIaGfsXhLFa+KjopyM4kgzlCPue1lydRlSNc4YAJK/Y7rIiRcX/cQtoPdhcF7jI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1736881421; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=AgLvY4Yqxv93JLq+I9d9qXSGhW5owB+tPXqiGJMRc+Y=; b=LuyUPLFEvhVchLI6VINAu68sLFstWQyPF486Yt5DSenLmjP12uVIOm3T3TzlVnk+PPl+2d7u6n2uu9+d29zY8hoq5szBNKOuMz8Ost1F3kn8mlDd+9U6FjOEMqQPP6UF8cDFFUC5b9waLnjna4tXNg1ltboOMt7MqHUrHlypc6M= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1736881421008287.09173379433764; Tue, 14 Jan 2025 11:03:41 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tXm8g-0005lj-0A; Tue, 14 Jan 2025 13:59:46 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tXm7w-0005fA-35 for qemu-devel@nongnu.org; Tue, 14 Jan 2025 13:59:03 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tXm7t-0002lJ-9H for qemu-devel@nongnu.org; Tue, 14 Jan 2025 13:58:59 -0500 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-494-Ra_N_3-vMd2piVquBHZJYA-1; Tue, 14 Jan 2025 13:58:54 -0500 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A166E1955F67; Tue, 14 Jan 2025 18:58:53 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.175]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 9190C19560A3; Tue, 14 Jan 2025 18:58:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1736881136; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=AgLvY4Yqxv93JLq+I9d9qXSGhW5owB+tPXqiGJMRc+Y=; b=SXYspgfqNfNOby3W9aBrwiIzSv6wLLHSJQD2LdpJsQS++GDOS0Z6Jy6TShnrIs/LGegwLg A1djtpjshxei+fTwa6l8LI933ptC5tzSmUIn/uPZMdbhDHJSO/6GDrgMtgKsZmC62UVoo9 WCeVX94XCb1fCYxHwQt60MWsGCq6Jr0= X-MC-Unique: Ra_N_3-vMd2piVquBHZJYA-1 X-Mimecast-MFC-AGG-ID: Ra_N_3-vMd2piVquBHZJYA From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Peter Maydell , Markus Armbruster , John Snow Subject: [PATCH v2 06/23] docs/qapidoc: add transmogrifier stub Date: Tue, 14 Jan 2025 13:58:23 -0500 Message-ID: <20250114185840.3058525-7-jsnow@redhat.com> In-Reply-To: <20250114185840.3058525-1-jsnow@redhat.com> References: <20250114185840.3058525-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -39 X-Spam_score: -4.0 X-Spam_bar: ---- X-Spam_report: (-4.0 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.063, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-1.794, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1736881423244019000 Content-Type: text/plain; charset="utf-8" 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 --- docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d622398f1da..dc72f3fd3f3 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -452,9 +452,9 @@ def _parse_text_into_node(self, doctext, node): rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.li= ne) self._sphinx_directive.do_parse(rstlist, node) =20 - 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 =20 =20 # Turn the black formatter on for the rest of the file. @@ -503,7 +503,10 @@ class QAPIDocDirective(NestedDirective): =20 required_argument =3D 1 optional_arguments =3D 1 - option_spec =3D {"qapifile": directives.unchanged_required} + option_spec =3D { + "qapifile": directives.unchanged_required, + "transmogrify": directives.flag, + } has_content =3D False =20 def new_serialno(self): @@ -511,10 +514,24 @@ def new_serialno(self): env =3D self.state.document.settings.env return "qapidoc-%d" % env.new_serialno("qapidoc") =20 + def transmogrify(self, schema) -> nodes.Element: + raise NotImplementedError + + def legacy(self, schema) -> nodes.Element: + vis =3D 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 =3D self.state.document.settings.env qapifile =3D env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir =3D os.path.dirname(qapifile) + transmogrify =3D "transmogrify" in self.options =20 try: schema =3D QAPISchema(qapifile) @@ -522,20 +539,18 @@ def run(self): # First tell Sphinx about all the schema files that the # output documentation depends on (including 'qapifile' itself) schema.visit(QAPISchemaGenDepVisitor(env, qapidir)) - - vis =3D 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 =20 + if transmogrify: + contentnode =3D self.transmogrify(schema) + else: + contentnode =3D self.legacy(schema) + + return contentnode.children + =20 class QMPExample(CodeBlock, NestedDirective): """ --=20 2.47.1