From nobody Sat Feb 7 06:57:32 2026 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=1738797335; cv=none; d=zohomail.com; s=zohoarc; b=H2wjZ+LBDWOXgutiZuUYsGxHhajRE76heocPOgsh+TKevYSRHmOG0tZd6r5lnS3HAdizDCHyEL4m7IPYGx8xqSMUVuKmA+VeYksYKLwZ6rkILIIl8vkIlvLYXOn5B5hs4qvYlaFM+XU0Pwb3jrjQk26XX0rOPb4+26kGKFBjOtY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797335; 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=7rlY36oQtVSPyIz+C7TU5nD1O/rmrISF76rdDY3L36k=; b=beTzz5ReZW0pkQXHxDuNnaljrVOJkU76oDbItdM9/JLYn3VqBapq1JeVsntjqWKCZ+HhL47koebTCBe9LPo+Jyw2WJG/8NaDBxevtmOd9kVdrFKtkeTXbIMeJ27BZDK7e2oWWOa0470I9fMnRKC24DvOyJkhZwrOz9Gj0RTsRac= 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 1738797335518684.6721992077624; Wed, 5 Feb 2025 15:15:35 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZV-0001GY-1V; Wed, 05 Feb 2025 18:12:41 -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 1tfoZL-0001F5-A8 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:32 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoZJ-0005aj-St for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:31 -0500 Received: from mx-prod-mc-03.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-395-ENQ3uxTOMImZ_wEeITVSmQ-1; Wed, 05 Feb 2025 18:12:23 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9EE991956046; Wed, 5 Feb 2025 23:12:21 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2640C1800267; Wed, 5 Feb 2025 23:12:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797146; 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=7rlY36oQtVSPyIz+C7TU5nD1O/rmrISF76rdDY3L36k=; b=dav0/iozheJ2OaW9/A0Hh11BhrUSuaf4eloBXgfQK5lB82hNdb4QQuWJvfXXvFgmlMYh5x WJo67owaSj3Oe3VI3XMhK4NKIe6168Uq2SoK+5VGcvpOq3ugLyoSYe3/pGFxjuJ5deNadF eRKFFWeV88pRRDU8mI12XHRSC/38zus= X-MC-Unique: ENQ3uxTOMImZ_wEeITVSmQ-1 X-Mimecast-MFC-AGG-ID: ENQ3uxTOMImZ_wEeITVSmQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 01/42] docs/qapidoc: support header-less freeform sections Date: Wed, 5 Feb 2025 18:11:27 -0500 Message-ID: <20250205231208.1480762-2-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797337851019100 Content-Type: text/plain; charset="utf-8" The code as written can't handle if a header isn't found and will crash, because `node` will be uninitialized. If we don't have a section title, create a generic block to insert text into instead. (This patch also removes a lingering pylint warning in the QAPIDoc implementation that prevents getting a clean baseline to use for forthcoming additions.) I am not attempting to *fully* clean up the existing QAPIDoc implementation in pylint because I intend to delete it anyway; this patch merely accomplishes a baseline under a specific pylint configuration: PYTHONPATH=3D../../scripts/ pylint --disable=3Dfixme,too-many-lines,\ consider-using-f-string,missing-docstring,unused-argument,\ too-many-arguments,too-many-positional-arguments,\ too-many-public-methods \ qapidoc.py (under at least pylint 3.3.1; more robust tamping down of the environment needed to consistently perform checks will happen later - hopefully soon, sorry for the inconvenience.) This at least ensures there aren't regressions outside of these general warnings in the new qapidoc.py code to be committed. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5f96b46270b..5a4d7388b29 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -421,6 +421,8 @@ def freeform(self, doc): node =3D self._start_new_heading(heading, len(leader)) if text =3D=3D '': return + else: + node =3D nodes.container() =20 self._parse_text_into_node(text, node) self._cur_doc =3D None --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797450; cv=none; d=zohomail.com; s=zohoarc; b=XSOD6FgRcYA//oxVjSDM7HtK68SKEquRQ/cR7CigqUIEB4NiX45lBpE/q8/Nh+ljz2SR2AwF1PZ7VQUZqTkp6G6/eSkYZoB+gBjyFYFGnlzLR5TTlZgAIxwuEdgJozIQ5VEYEPtpfNiJOs7cLETZkUaeBk2Fs7vZI/YxLCHf8bY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797450; 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=GyiRxmydcU0/fOZaO5aRgfQNpoUwmviAK70kDpUDoAk=; b=UhRXHuZARswOvWN/sM3ajIgLNWpVj/xe/s0wkW8nSAOLBPtDxK0JWgN13Pzj1fQpC7W/Z/7e16yxoo5c3yBrq1RckQFUec0jAb6mw3NnXoXRvkUMZNWmLmExr1c/oW7x9npN6lWZZXA1p8fN4avM/7Wf4d8om9pzY/+mR2iLkKc= 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 1738797450988807.4084367532554; Wed, 5 Feb 2025 15:17:30 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZg-0001IH-An; Wed, 05 Feb 2025 18:12:53 -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 1tfoZR-0001GQ-D3 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:39 -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 1tfoZP-0005bQ-RJ for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:37 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-632-hI6tSBmUMyez9CfJnLNhqw-1; Wed, 05 Feb 2025 18:12:30 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id C97F11800982; Wed, 5 Feb 2025 23:12:28 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 5AEEA1800570; Wed, 5 Feb 2025 23:12:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797154; 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=GyiRxmydcU0/fOZaO5aRgfQNpoUwmviAK70kDpUDoAk=; b=OkM6gObNihpCPOtPthf2iLZJ9w+WkhyMyEI6fBjGI2agKdZ9wIj/Srav50Gn45ITff7gdS 1F1Cxw5F54VKZH9P/NIWRiCLVxe5mNd+Vrkw5x4no+sVAFF0Vc+YJegfSdLexq7A3/wIF4 mzKMKzl+Dz9FWN3jEZdUV6+nPA8SCW8= X-MC-Unique: hI6tSBmUMyez9CfJnLNhqw-1 X-Mimecast-MFC-AGG-ID: hI6tSBmUMyez9CfJnLNhqw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 02/42] qapi/parser: adjust info location for doc body section Date: Wed, 5 Feb 2025 18:11:28 -0500 Message-ID: <20250205231208.1480762-3-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797452201019100 Content-Type: text/plain; charset="utf-8" Instead of using the info object for the doc block as a whole (which always points to the very first line of the block), update the info pointer for each call to ensure_untagged_section when the existing section is otherwise empty. This way, Sphinx error information will match precisely to where the text actually starts. For example, this patch will move the info pointer for the "Hello!" untagged section ... > ## <-- from here ... > # Hello! <-- ... to here. > ## Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/parser.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index adc85b5b394..36cb64a677a 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -687,7 +687,11 @@ def end(self) -> None: def ensure_untagged_section(self, info: QAPISourceInfo) -> None: if self.all_sections and not self.all_sections[-1].tag: # extend current section - self.all_sections[-1].text +=3D '\n' + section =3D self.all_sections[-1] + if not section.text: + # Section is empty so far; update info to start *here*. + section.info =3D info + section.text +=3D '\n' return # start new section section =3D self.Section(info) --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797475; cv=none; d=zohomail.com; s=zohoarc; b=cBVhxecTcEHRgVDzDru7ThNuWIzOYY/yIZLxpRy5cs+3OZsgnhGLckIRoB/IkqkMyKF8QaXMnO0j/NH0AltrnoNfn6MlnP/GT18QMWryDp0wj5cytzGTobbWGubfuywiLWyfFbXWWbynw0czImMFwVTlB/a/+Y5nDFwu9b8NBNY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797475; 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=idbJdwJ8CDyE+xVdzPTbisC279pESEqsJVDljvElmiw=; b=Ogy/wfe0Cc3tXRrZh6r4vLdjQ17/B/sCmdUqDQWwFIIoL82Gyu6WR29i4imWjPYa8XQzLksESza7EAlf5nWkyjm7hXCIjIp5xlAHnPqoX7gfzCKRlbNLQJ2tuvUarYYCyaXgBwXovASY3LgH5HcGZONgSBdUycOyLfcvim4c8SY= 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 173879747574450.544505519003565; Wed, 5 Feb 2025 15:17:55 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZg-0001IP-B8; Wed, 05 Feb 2025 18:12:54 -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 1tfoZY-0001Hn-Vi for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:46 -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 1tfoZW-0005bq-Lw for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:43 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-116-u6sy38uLMwilO3-bmKIMVw-1; Wed, 05 Feb 2025 18:12:36 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 25C761800878; Wed, 5 Feb 2025 23:12:34 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 45A4B1800267; Wed, 5 Feb 2025 23:12:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797161; 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=idbJdwJ8CDyE+xVdzPTbisC279pESEqsJVDljvElmiw=; b=LdW/5qON/ZdtRFHnAYcMvjOFKcohf5VsbB75ogcuQybPUuQsYDf4bTP4SOzW7ZWpRek+Ig QcB5vHvmgBOxkz6TUJLGj352PCDYJODzTgDj9FLj4eF+9XCr68yNS9YwyQMDFIpyXVbXJQ ZNxZXs5RHD1MPDpdFy8aOKY02+D1sB4= X-MC-Unique: u6sy38uLMwilO3-bmKIMVw-1 X-Mimecast-MFC-AGG-ID: u6sy38uLMwilO3-bmKIMVw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 03/42] docs/qapidoc: remove example section support Date: Wed, 5 Feb 2025 18:11:29 -0500 Message-ID: <20250205231208.1480762-4-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797475987019000 Content-Type: text/plain; charset="utf-8" Since commit 3c5f6114 (qapi: remove "Example" doc section), Example sections no longer exist, so this support in qapidoc is now dead code. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5a4d7388b29..61997fd21af 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -254,10 +254,6 @@ def _nodes_for_features(self, doc): section +=3D dlnode return [section] =20 - def _nodes_for_example(self, exampletext): - """Return list of doctree nodes for a code example snippet""" - return [nodes.literal_block(exampletext, exampletext)] - def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist =3D [] @@ -275,10 +271,7 @@ def _nodes_for_sections(self, doc): continue =20 snode =3D self._make_section(section.tag) - if section.tag.startswith('Example'): - snode +=3D self._nodes_for_example(dedent(section.text)) - else: - self._parse_text_into_node(dedent(section.text), snode) + self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797227; cv=none; d=zohomail.com; s=zohoarc; b=kuPFm24rVbxoZW4EbMLg3fMoFVPbrjateKWYutciYD1QCKyydZVR1YEGXxWGS/DLeMDwdgKEWXdIVmnzqPDo7W3Xv3hUzP1sFUZ3Pj52xMc660OIAGCLg6fu9C9AMg9BWsFEYtZ51nhTxHcv9SGdZP67/FGa2xqcHlKCYTcdV14= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797227; 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=zMLbHhizeluJkqGGXl5VHpMeg84p0Ut5PhJj+s5R06k=; b=jv92RpHVldPamjTXUGXhHOPFuKdv/G0JRwBMNflgAK1mJjSHjuIgj1LFIIxUMtiIuQ6bPphTcU8EXmjiEeFhQ2WQqksw8Bz+N5A/NZntifaOL+IS+95yT5CRjdLV9cCkWj/e3heBwP6ty2C1lJNt5Msai/SAkktkPyiKv+88Vwo= 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 1738797227983251.47593299374228; Wed, 5 Feb 2025 15:13:47 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZm-0001Jx-UY; Wed, 05 Feb 2025 18:12:58 -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 1tfoZf-0001IR-Ur for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:52 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoZd-0005cb-RR for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:51 -0500 Received: from mx-prod-mc-03.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-99-lQiFtOxXN1aj7MzRhcLfDA-1; Wed, 05 Feb 2025 18:12:44 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6C3B319560B6; Wed, 5 Feb 2025 23:12:41 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7F4461800570; Wed, 5 Feb 2025 23:12:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797167; 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=zMLbHhizeluJkqGGXl5VHpMeg84p0Ut5PhJj+s5R06k=; b=T8NPUMc9+0mFJH0q8V9nRuP4ug/UUV/C8xdyoeMwlmqAnWZnA58C0mR7YpqSmUgOoWdoCH tgp3btUsaWc10HZU/8bNvT3OC5C7XuJFe/Xmq5JuCtHmI6j3T8kUvETOAVlu/l0ewg8HaZ IJ2rJyZ9JJK/uxtLxI3nM5HQ+FszJew= X-MC-Unique: lQiFtOxXN1aj7MzRhcLfDA-1 X-Mimecast-MFC-AGG-ID: lQiFtOxXN1aj7MzRhcLfDA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 04/42] qapi: expand tags to all doc sections Date: Wed, 5 Feb 2025 18:11:30 -0500 Message-ID: <20250205231208.1480762-5-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797229794019100 Content-Type: text/plain; charset="utf-8" This patch adds an explicit section "kind" to all QAPIDoc sections. Members/Features are now explicitly marked as such, with the name now being stored in a dedicated "name" field (which qapidoc.py was not actually using anyway.) The qapi-schema tests are updated to account for the new section names; mostly "TODO" becomes "Todo" and `None` becomes "Plain". Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 7 ++- scripts/qapi/parser.py | 109 ++++++++++++++++++++++++--------- tests/qapi-schema/doc-good.out | 10 +-- tests/qapi-schema/test-qapi.py | 2 +- 4 files changed, 90 insertions(+), 38 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 61997fd21af..d622398f1da 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -35,6 +35,7 @@ from docutils.statemachine import ViewList from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor +from qapi.parser import QAPIDoc from qapi.schema import QAPISchema =20 from sphinx import addnodes @@ -258,11 +259,11 @@ def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist =3D [] for section in doc.sections: - if section.tag and section.tag =3D=3D 'TODO': + if section.kind =3D=3D QAPIDoc.Kind.TODO: # Hide TODO: sections continue =20 - if not section.tag: + if section.kind =3D=3D QAPIDoc.Kind.PLAIN: # Sphinx cannot handle sectionless titles; # Instead, just append the results to the prior section. container =3D nodes.container() @@ -270,7 +271,7 @@ def _nodes_for_sections(self, doc): nodelist +=3D container.children continue =20 - snode =3D self._make_section(section.tag) + snode =3D self._make_section(section.kind.name.title()) self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 36cb64a677a..c3004aa70c6 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -15,6 +15,7 @@ # See the COPYING file in the top-level directory. =20 from collections import OrderedDict +import enum import os import re from typing import ( @@ -575,7 +576,10 @@ def get_doc(self) -> 'QAPIDoc': ) raise QAPIParseError(self, emsg) =20 - doc.new_tagged_section(self.info, match.group(1)) + doc.new_tagged_section( + self.info, + QAPIDoc.Kind.from_string(match.group(1)) + ) text =3D line[match.end():] if text: doc.append_line(text) @@ -586,7 +590,7 @@ def get_doc(self) -> 'QAPIDoc': self, "unexpected '=3D' markup in definition documentati= on") else: - # tag-less paragraph + # plain paragraph(s) doc.ensure_untagged_section(self.info) doc.append_line(line) line =3D self.get_doc_paragraph(doc) @@ -635,14 +639,37 @@ class QAPIDoc: Free-form documentation blocks consist only of a body section. """ =20 + class Kind(enum.Enum): + PLAIN =3D 0 + MEMBER =3D 1 + FEATURE =3D 2 + RETURNS =3D 3 + ERRORS =3D 4 + SINCE =3D 5 + TODO =3D 6 + + @staticmethod + def from_string(kind: str) -> 'QAPIDoc.Kind': + return QAPIDoc.Kind[kind.upper()] + + def text_required(self) -> bool: + # Only "plain" sections can be empty + return self.value not in (0,) + + def __str__(self) -> str: + return self.name.title() + class Section: # pylint: disable=3Dtoo-few-public-methods - def __init__(self, info: QAPISourceInfo, - tag: Optional[str] =3D None): + def __init__( + self, + info: QAPISourceInfo, + kind: 'QAPIDoc.Kind', + ): # section source info, i.e. where it begins self.info =3D info - # section tag, if any ('Returns', '@name', ...) - self.tag =3D tag + # section kind + self.kind =3D kind # section text without tag self.text =3D '' =20 @@ -650,8 +677,14 @@ def append_line(self, line: str) -> None: self.text +=3D line + '\n' =20 class ArgSection(Section): - def __init__(self, info: QAPISourceInfo, tag: str): - super().__init__(info, tag) + def __init__( + self, + info: QAPISourceInfo, + kind: 'QAPIDoc.Kind', + name: str + ): + super().__init__(info, kind) + self.name =3D name self.member: Optional['QAPISchemaMember'] =3D None =20 def connect(self, member: 'QAPISchemaMember') -> None: @@ -663,7 +696,9 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): # definition doc's symbol, None for free-form doc self.symbol: Optional[str] =3D symbol # the sections in textual order - self.all_sections: List[QAPIDoc.Section] =3D [QAPIDoc.Section(info= )] + self.all_sections: List[QAPIDoc.Section] =3D [ + QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) + ] # the body section self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] # dicts mapping parameter/feature names to their description @@ -680,12 +715,17 @@ def __init__(self, info: QAPISourceInfo, symbol: Opti= onal[str] =3D None): def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') - if section.tag is not None and section.text =3D=3D '': + if section.kind.text_required() and section.text =3D=3D '': raise QAPISemError( - section.info, "text required after '%s:'" % section.ta= g) + section.info, "text required after '%s:'" % section.ki= nd) =20 - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: - if self.all_sections and not self.all_sections[-1].tag: + def ensure_untagged_section( + self, + info: QAPISourceInfo, + ) -> None: + kind =3D QAPIDoc.Kind.PLAIN + + if self.all_sections and self.all_sections[-1].kind =3D=3D kind: # extend current section section =3D self.all_sections[-1] if not section.text: @@ -693,46 +733,56 @@ def ensure_untagged_section(self, info: QAPISourceInf= o) -> None: section.info =3D info section.text +=3D '\n' return + # start new section - section =3D self.Section(info) + section =3D self.Section(info, kind) self.sections.append(section) self.all_sections.append(section) =20 - def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: - section =3D self.Section(info, tag) - if tag =3D=3D 'Returns': + def new_tagged_section( + self, + info: QAPISourceInfo, + kind: 'QAPIDoc.Kind', + ) -> None: + section =3D self.Section(info, kind) + if kind =3D=3D QAPIDoc.Kind.RETURNS: if self.returns: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.returns =3D section - elif tag =3D=3D 'Errors': + elif kind =3D=3D QAPIDoc.Kind.ERRORS: if self.errors: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.errors =3D section - elif tag =3D=3D 'Since': + elif kind =3D=3D QAPIDoc.Kind.SINCE: if self.since: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.since =3D section self.sections.append(section) self.all_sections.append(section) =20 - def _new_description(self, info: QAPISourceInfo, name: str, - desc: Dict[str, ArgSection]) -> None: + def _new_description( + self, + info: QAPISourceInfo, + name: str, + kind: 'QAPIDoc.Kind', + desc: Dict[str, ArgSection] + ) -> None: if not name: raise QAPISemError(info, "invalid parameter name") if name in desc: raise QAPISemError(info, "'%s' parameter name duplicated" % na= me) - section =3D self.ArgSection(info, '@' + name) + section =3D self.ArgSection(info, kind, name) self.all_sections.append(section) desc[name] =3D section =20 def new_argument(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, self.args) + self._new_description(info, name, QAPIDoc.Kind.MEMBER, self.args) =20 def new_feature(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, self.features) + self._new_description(info, name, QAPIDoc.Kind.FEATURE, self.featu= res) =20 def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) @@ -744,8 +794,9 @@ def connect_member(self, member: 'QAPISchemaMember') ->= None: raise QAPISemError(member.info, "%s '%s' lacks documentation" % (member.role, member.name)) - self.args[member.name] =3D QAPIDoc.ArgSection( - self.info, '@' + member.name) + section =3D QAPIDoc.ArgSection( + self.info, QAPIDoc.Kind.MEMBER, member.name) + self.args[member.name] =3D section self.args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index ec277be91e9..2d33a305ee7 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -110,7 +110,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=3Denum-member-feat a member feature - section=3DNone + section=3DPlain @two is undocumented doc symbol=3DBase body=3D @@ -168,15 +168,15 @@ description starts on the same line a feature feature=3Dcmd-feat2 another feature - section=3DNone + section=3DPlain .. note:: @arg3 is undocumented section=3DReturns @Object section=3DErrors some - section=3DTODO + section=3DTodo frobnicate - section=3DNone + section=3DPlain .. admonition:: Notes =20 - Lorem ipsum dolor sit amet @@ -209,7 +209,7 @@ If you're bored enough to read this, go see a video of = boxed cats a feature feature=3Dcmd-feat2 another feature - section=3DNone + section=3DPlain .. qmp-example:: =20 -> "this example" diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index 7e3f9f4aa1f..bca924309be 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -131,7 +131,7 @@ def test_frontend(fname): for feat, section in doc.features.items(): print(' feature=3D%s\n%s' % (feat, section.text)) for section in doc.sections: - print(' section=3D%s\n%s' % (section.tag, section.text)) + print(' section=3D%s\n%s' % (section.kind, section.text)) =20 =20 def open_test_result(dir_name, file_name, update): --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797212; cv=none; d=zohomail.com; s=zohoarc; b=kFQTKDw0l+2g+onCR+R34W4J4wQ1rVF6pnwf6HqPAP9eqzi8kqrsmesV42wSOygXuXiQRuHX607ViyBTPJWl3RVbh/LjOTLPEkBdwH23TYDwqTzIh85wuAYZH6XuSav3icMGDwzo1tKpcFVFfIF/dT2UuPY6Vb6vWlMVVeDeY2k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797212; 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=P4u6zr/yTgA0fR7lHxi1wVrW/cq6d9BZSYCfB7ZmX1k=; b=IJX6GnhbdY04SyjMgLZs04x3rdySVl8vvB5+y3iJK+Fh/x4lj2y0Am/YmLnR/6A/OFuniK/Juwj4mfFI1jSJwbYzxZB/W6BvamaeNkgTXxMmEVID7rYFFzi9z/WNPeSiVLCv4nqLwmKewJKCtc6WuJ/Pnz+ycY4lewyh6vzguz4= 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 1738797212371430.58002039687847; Wed, 5 Feb 2025 15:13:32 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZn-0001K8-Vd; Wed, 05 Feb 2025 18:12:59 -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 1tfoZk-0001Iy-2s for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:56 -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 1tfoZi-0005ct-2j for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:12:55 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-294-Vz-gkZIANTCKSA7fgnt2Hw-1; Wed, 05 Feb 2025 18:12:48 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A080C1800268; Wed, 5 Feb 2025 23:12:46 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D5A711800570; Wed, 5 Feb 2025 23:12:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797173; 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=P4u6zr/yTgA0fR7lHxi1wVrW/cq6d9BZSYCfB7ZmX1k=; b=Wnu3AyEjPT3lzHzSxVqQsdxOOCorPjb5tNAJAY0IO91WJGRFOYh0lOdFm85oVJI0glFYfo aUuqkaer4/qHPZn0zn1iKMGoYhK9WXXplR0TnXhXKtdz5njXSlJpCu3RHTwoA8OsUatAo7 ZhYM4zFEJSslmS707/qaVbR3SAj6/Lo= X-MC-Unique: Vz-gkZIANTCKSA7fgnt2Hw-1 X-Mimecast-MFC-AGG-ID: Vz-gkZIANTCKSA7fgnt2Hw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 05/42] qapi/schema: add __repr__ to QAPIDoc.Section Date: Wed, 5 Feb 2025 18:11:31 -0500 Message-ID: <20250205231208.1480762-6-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797213830019100 Content-Type: text/plain; charset="utf-8" Makes debugging far more pleasant when you can just print(section) and get something reasonable to display. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/parser.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c3004aa70c6..af5d7bf892c 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -673,6 +673,9 @@ def __init__( # section text without tag self.text =3D '' =20 + def __repr__(self) -> str: + return f"" + def append_line(self, line: str) -> None: self.text +=3D line + '\n' =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797251; cv=none; d=zohomail.com; s=zohoarc; b=aEYhHk6zhjNKcV5tt6mdM5nU+yjzLSk7JosorCQ5894LoM2NiZ8f3gbNa1DjeJC1/u65KnOANguQ0gPPbhG0SDzCwn5DAADSgN8fsGicR19RKEhum/l3H8YOmP3pd+EmFWoshHOxqnI6G2oPr4F+kNRYJ+TMLKypNELFofk38DE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797251; 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=Wa1Xi1ebmSpbrQKxKvSJI+EMuuyJ3SeCmG/4SFx/eQw=; b=Pfd1O9+pqQapCGH8KvvWWt0R+aC+xXPsONJi8Wod9EN7duR8T9r6EBdi/1ZofCn4sKyrkZnYMkBliDPuHYekVjluMe6WsdqPSgkWDMu7Jmv62zEVQ8vUAEQWTkD5nqhemGUkZnasyPMRzX+aoge0azFycnHYZj5z0iS5yP/+mu8= 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 1738797251772272.865208602144; Wed, 5 Feb 2025 15:14:11 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoZq-0001Kk-V4; Wed, 05 Feb 2025 18:13:02 -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 1tfoZp-0001KS-Ae for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:01 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoZm-0005dP-SS for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:00 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-493-NLdcNOnUOTeEbRTbEaFr7Q-1; Wed, 05 Feb 2025 18:12:54 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E93601800878; Wed, 5 Feb 2025 23:12:52 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 55D931800267; Wed, 5 Feb 2025 23:12:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797177; 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=Wa1Xi1ebmSpbrQKxKvSJI+EMuuyJ3SeCmG/4SFx/eQw=; b=T1lTbBeFEgMeeR46etM9CjIuV+W4w8rejnl9nxNaKXxYVmUxfKqyT5/nl5ZF9WJAd6P+8b /L5UL2TQr3GeEcar9B+1GoJTKjbpicnRrllVs62J9zOPskyK/C4eHAqN/AQCLcjrzruKfy HBMUZLj0gu/rdxkL9gV2QO2uc5hRfww= X-MC-Unique: NLdcNOnUOTeEbRTbEaFr7Q-1 X-Mimecast-MFC-AGG-ID: NLdcNOnUOTeEbRTbEaFr7Q From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 06/42] docs/qapidoc: add transmogrifier stub Date: Wed, 5 Feb 2025 18:11:32 -0500 Message-ID: <20250205231208.1480762-7-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797253253019000 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 based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- 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.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797239; cv=none; d=zohomail.com; s=zohoarc; b=QNt3MRTWQveZFLyZfgF6USY0dA8eqLdMtHMm8Se+eTWk9B+IjfczZNq/8S5xqvxFzL9yeN22joPHokr/KuDqQK1nAokQigjAtls2lpgJDlPMZIL3kHkynMDnXaBg/C03CLw8FAi63YD+bbL2S7pvUjXgv2rk3oaqU3HNaidRa1o= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797239; 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=IWc3uci1tbaXqVQSooxoyAq24qqzJssEov/pFIs//EE=; b=Dci5lPWKZtq5Drcw5Jsujhst6zTJTQp3NoZfZoGeub46lK15MTFszYQ535yhYnvJG6Gg8KUR1T3pnwy1MrGNu/iGdQj+vk/iMHjr9NSU1SUkNRmMNydDS8e/FzNug2RHj7zf4MloQL/HYqUSvD++GlVZ1+BkRGWtRpJlauyttfc= 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 1738797239874667.4576633518834; Wed, 5 Feb 2025 15:13:59 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoa3-0001M5-6x; Wed, 05 Feb 2025 18:13:15 -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 1tfoa0-0001LN-T7 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:12 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoZu-0005eS-D8 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:11 -0500 Received: from mx-prod-mc-02.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-157-2H3URj8dPAyWKM_K6IZ-wA-1; Wed, 05 Feb 2025 18:13:02 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B72561956086; Wed, 5 Feb 2025 23:13:00 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 9E6CD1800570; Wed, 5 Feb 2025 23:12:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797185; 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=IWc3uci1tbaXqVQSooxoyAq24qqzJssEov/pFIs//EE=; b=XXmDqk1R/O+1fNzrWUiz0OXw6rwY3wm9nzL6RJjjYTDcvxpM0jqPRfc5dWDQ6xZ+3Ej6vP QIeYwZoyuuhUSx+rBhvXQ9n5uyrGlb/KKl3LabaxtC2ue0Ec39Amb3JxZ6zHKA+FkOaUau Bs23+BrBnehVNBMAg9TmrZ2RrELlJJs= X-MC-Unique: 2H3URj8dPAyWKM_K6IZ-wA-1 X-Mimecast-MFC-AGG-ID: 2H3URj8dPAyWKM_K6IZ-wA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 07/42] docs/qapidoc: add transmogrifier class stub Date: Wed, 5 Feb 2025 18:11:33 -0500 Message-ID: <20250205231208.1480762-8-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797241641019100 Content-Type: text/plain; charset="utf-8" Add the beginnings of the Transmogrifier class by adding the rST conversion helpers that will be used to build the virtual rST document. This version of the class does not actually "do anything" yet; each individual feature is added one-at-a-time in the forthcoming commits. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 66 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index dc72f3fd3f3..6593c3f28cd 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -24,6 +24,7 @@ https://www.sphinx-doc.org/en/master/development/index.html """ =20 +from contextlib import contextmanager import os import re import sys @@ -32,11 +33,12 @@ =20 from docutils import nodes from docutils.parsers.rst import Directive, directives -from docutils.statemachine import ViewList +from docutils.statemachine import StringList, ViewList from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.parser import QAPIDoc from qapi.schema import QAPISchema +from qapi.source import QAPISourceInfo =20 from sphinx import addnodes from sphinx.directives.code import CodeBlock @@ -61,6 +63,68 @@ def dedent(text: str) -> str: return lines[0] + textwrap.dedent("".join(lines[1:])) =20 =20 +class Transmogrifier: + def __init__(self, schema): + self._result =3D StringList() + self.indent =3D 0 + + # General-purpose rST generation functions + + def get_indent(self) -> str: + return " " * self.indent + + @contextmanager + def indented(self): + self.indent +=3D 1 + try: + yield + finally: + self.indent -=3D 1 + + def add_line_raw(self, line: str, source: str, *lineno: int) -> None: + """Append one line of generated reST to the output.""" + + # NB: Sphinx uses zero-indexed lines; subtract one. + lineno =3D tuple((n - 1 for n in lineno)) + + if line.strip(): + # not a blank line + self._result.append( + self.get_indent() + line.rstrip("\n"), source, *lineno + ) + else: + self._result.append("", source, *lineno) + + def add_line(self, content: str, info: QAPISourceInfo) -> None: + # NB: We *require* an info object; this works out OK because we + # don't document built-in objects that don't have + # one. Everything else should. + assert info + self.add_line_raw(content, info.fname, info.line) + + def add_lines( + self, + content: str, + info: QAPISourceInfo, + ) -> None: + assert info + lines =3D content.splitlines(True) + for i, line in enumerate(lines): + self.add_line_raw(line, info.fname, info.line + i) + + def ensure_blank_line(self) -> None: + # Empty document -- no blank line required. + if not self._result: + return + + # Last line isn't blank, add one. + if self._result[-1].strip(): # pylint: disable=3Dno-member + fname, line =3D self._result.info(-1) + # New blank line is credited to one-after the current last lin= e. + # +2: correct for zero/one index, then increment by one. + self.add_line_raw("", fname, line + 2) + + # Disable black auto-formatter until re-enabled: # fmt: off =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797214; cv=none; d=zohomail.com; s=zohoarc; b=NNg16/n3DcOnCcL8b570FnXTJgWVo34Ixs0GyncCtmC64S/uKid0zRPOtRGXppnYPGV6iymCPxL62XOAJvKZm+H3yHjxPRD5MFTQOvNqAIFgRpHcEBc5irAsXyf9mPAkfCN8/UUlz6c4Zbh6F1Hxwex37P5+r1k7ekcCC9XIThU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797214; 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=YPdQhhY7g06QSI0CNsj/3j2/Jxzig/2jc44tgQnvFOg=; b=kRbbXw5DCTvbdf9Q7yXzqMf/FLGDL6hjtozg1Op7eDi78DmjVmi4klMfh+dD9z23O+dYX76gcA+uTlpoz+VDaLiQvbCKYD002DzyWMasgnbzbKNOpmb1FqzXqIbwRBrxZlzNYuZ5HSSxcnTsc8KIia/fBstD1Qb3L5YMq9tsd/I= 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 1738797213981787.550061835823; Wed, 5 Feb 2025 15:13:33 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoa9-0001Tj-12; Wed, 05 Feb 2025 18:13:21 -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 1tfoa7-0001Mz-Le for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:19 -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 1tfoa1-0005ep-81 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:19 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-540-COValA7COb6ttUn_032CFA-1; Wed, 05 Feb 2025 18:13:08 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B32801800871; Wed, 5 Feb 2025 23:13:06 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 694731800570; Wed, 5 Feb 2025 23:13:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797192; 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=YPdQhhY7g06QSI0CNsj/3j2/Jxzig/2jc44tgQnvFOg=; b=Iji/HyAEEvuPv8ao16OG8TidSoe/KyOCZlr7h0ipTJn4olrYrR8+7KwX/JSbBZK2OLVABZ D3e5xhe+YVv0YyUi78VuNF2FzFgrv3KKvRDfHZIiEin1v70sD44Y8/RcXu3my0wMFne532 9N+w3WYfh6upift8t+DIATx3tRl0dDI= X-MC-Unique: COValA7COb6ttUn_032CFA-1 X-Mimecast-MFC-AGG-ID: COValA7COb6ttUn_032CFA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 08/42] docs/qapidoc: add visit_module() method Date: Wed, 5 Feb 2025 18:11:34 -0500 Message-ID: <20250205231208.1480762-9-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797215382019000 Content-Type: text/plain; charset="utf-8" This method annotates the start of a new module, crediting the source location to the first line of the module file. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6593c3f28cd..658eae3e386 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,6 +26,7 @@ =20 from contextlib import contextmanager import os +from pathlib import Path import re import sys import textwrap @@ -124,6 +125,14 @@ def ensure_blank_line(self) -> None: # +2: correct for zero/one index, then increment by one. self.add_line_raw("", fname, line + 2) =20 + # Transmogrification core methods + + def visit_module(self, path: str) -> None: + name =3D Path(path).stem + # module directives are credited to the first line of a module fil= e. + self.add_line_raw(f".. qapi:module:: {name}", path, 1) + self.ensure_blank_line() + =20 # Disable black auto-formatter until re-enabled: # fmt: off --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797228; cv=none; d=zohomail.com; s=zohoarc; b=n8GJkYtgip2LYsEWqaLsQH5mHsL5WhDettOn3lQd+TZM8Le7ZP0SOgU/5fwFqhCJ+u1AtNoeNjZ9Zh3AXkN/F/O71OceO2AxWIbegNsepNcMPCWoWAgk6rVYTkEqWQMOGl6MWDtlN17Q4+aTlcuCVZUUK4dXNxuSF212vfnGTLc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797228; 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=FhNc4XlKtZhVDqpp/h1XYzOnc0rVdthJ98dnkqQG2fU=; b=EG/yUYNUtx+4qs5LoJlQpZZ39U0XDsjWMSuh7ul/Ppge7EblTKYrVbWb6F6V9KI3+u17jiwJ7ChPvAPzQ8KmTpn2qO/7aMqMFfL8arGOut9JzRPhItdt0vkeyoBXIzs2wAZjvYpezJztPj4qJuL11xVFinjUPvqm/W/YevQ+f/Y= 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 17387972282626.041679778885623; Wed, 5 Feb 2025 15:13:48 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoaC-0001XL-GY; Wed, 05 Feb 2025 18:13:24 -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 1tfoa9-0001VY-EW for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:21 -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 1tfoa7-0005fI-Ow for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:21 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-356-6fKgh3RmPbSxYoPs9pfWzw-1; Wed, 05 Feb 2025 18:13:14 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 403C91800879; Wed, 5 Feb 2025 23:13:12 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4DAF41800570; Wed, 5 Feb 2025 23:13:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797198; 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=FhNc4XlKtZhVDqpp/h1XYzOnc0rVdthJ98dnkqQG2fU=; b=P/IyIcId5JgaUWoI4Yk7QWxYxupoGNcTeA6dpzz+tJd3jgkEJa1Q4I10SygIGuDuYxuLZN FSj2qQHKe0DkkN1L1xxK3+G6U09cQP1wq2dySpEqFXjjT5B+td5jebWUh2eva23GDKpRH3 tfG3GlVug9RlsWp1k0aMuiSkd8tLdIg= X-MC-Unique: 6fKgh3RmPbSxYoPs9pfWzw-1 X-Mimecast-MFC-AGG-ID: 6fKgh3RmPbSxYoPs9pfWzw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 09/42] qapi/source: allow multi-line QAPISourceInfo advancing Date: Wed, 5 Feb 2025 18:11:35 -0500 Message-ID: <20250205231208.1480762-10-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797229636019100 Content-Type: text/plain; charset="utf-8" This is for the sake of the new rST generator (the "transmogrifier") so we can advance multiple lines on occasion while keeping the generated<-->source mappings accurate. next_line now simply takes an optional n parameter which chooses the number of lines to advance. RFC: Here's the exorbitant detail on why I want this: This is used mainly when converting section syntax in free-form documentation to more traditional rST section header syntax, which does not always line up 1:1 for line counts. For example: ``` ## # =3D Section <-- Info is pointing here, "L1" # # Lorem Ipsum ## ``` would be transformed to rST as: ``` =3D=3D=3D=3D=3D=3D=3D <-- L1 Section <-- L1 =3D=3D=3D=3D=3D=3D=3D <-- L1 <-- L2 Lorem Ipsum <-- L3 ``` After consuming the single "Section" line from the source, we want to advance the source pointer to the next non-empty line which requires jumping by more than one line. Signed-off-by: John Snow Reviewed-by: Markus Armbruster based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/source.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py index 7b379fdc925..ffdc3f482ac 100644 --- a/scripts/qapi/source.py +++ b/scripts/qapi/source.py @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: self.defn_meta =3D meta self.defn_name =3D name =20 - def next_line(self: T) -> T: + def next_line(self: T, n: int =3D 1) -> T: info =3D copy.copy(self) - info.line +=3D 1 + info.line +=3D n return info =20 def loc(self) -> str: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797249; cv=none; d=zohomail.com; s=zohoarc; b=Zw2FrWOwm5PcSecpuizRgeUmpDYPjZnkHm3ObrvZhhdaJmDNEYDCOllGy81SNnjz9iK58tvnZgB7GxXLQFgqGYl0J5JAlY8u5J0i35qyKS6kDnMTyWKjcyD2doyjrcuVI98KTYqXxzwJOj51HemuLl7sO4DGVZxbLgQn3nOVXHA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797249; 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=Y4NwkAqiVaH5YimagugqJ5APb5BOWKEEhKm2N7RFwyI=; b=f1DZZb8a7Cg1W3zvDeDZEFtcTuZFnq/FvROjBs1COi8UakOhWTgZ0ze3aZeh0YWHQMN/GsqmNap6gA3HWx1+hJCTfz4CEbbdlmoJE1NcZyNRXtWq8ds5ikF9r190PdyOQ3a2EnhUscvKstvxyj3YBiYcoI5tkG+mghiF5c5lu9Q= 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 1738797249948270.8694538396668; Wed, 5 Feb 2025 15:14:09 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoaF-0001b8-10; Wed, 05 Feb 2025 18:13:27 -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 1tfoaC-0001YY-ND for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:24 -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 1tfoaA-0005fm-Rt for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:24 -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-692-hnQwiie9N4ugTEgAFQP2UA-1; Wed, 05 Feb 2025 18:13:19 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 5AEDD19560A6; Wed, 5 Feb 2025 23:13:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D0F301800267; Wed, 5 Feb 2025 23:13:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797202; 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=Y4NwkAqiVaH5YimagugqJ5APb5BOWKEEhKm2N7RFwyI=; b=fOloSKY2G1TWsPY6N6kbP1TRBobrm61OF8zkKhb462tRMVbRXU9RvvqW3Z2zndR63Y0izh tNg52YtbI3thLZWulpOhxF5CWnz2new6iyvCykuvKDKs3attsLw1J/KDdxJBRbtzL8qmgt PW490a6q3Xv+3KXwGr+DDnxgCeXUUiw= X-MC-Unique: hnQwiie9N4ugTEgAFQP2UA-1 X-Mimecast-MFC-AGG-ID: hnQwiie9N4ugTEgAFQP2UA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 10/42] docs/qapidoc: add visit_freeform() method Date: Wed, 5 Feb 2025 18:11:36 -0500 Message-ID: <20250205231208.1480762-11-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797251644019100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 47 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 658eae3e386..c42cc3705aa 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -133,6 +133,53 @@ def visit_module(self, path: str) -> None: self.add_line_raw(f".. qapi:module:: {name}", path, 1) self.ensure_blank_line() =20 + def visit_freeform(self, doc) -> None: + # TODO: Once the old qapidoc transformer is deprecated, freeform + # sections can be updated to pure rST, and this transformed remove= d. + # + # For now, translate our micro-format into rST. Code adapted + # from Peter Maydell's freeform(). + + assert len(doc.all_sections) =3D=3D 1, doc.all_sections + body =3D doc.all_sections[0] + text =3D body.text + info =3D doc.info + + if re.match(r"=3D+ ", text): + # Section/subsection heading (if present, will always be the + # first line of the block) + (heading, _, text) =3D text.partition("\n") + (leader, _, heading) =3D heading.partition(" ") + level =3D len(leader) + 1 # Implicit +1 for heading in .rST s= tub + + # https://www.sphinx-doc.org/en/master/usage/restructuredtext/= basics.html#sections + markers =3D { + 1: "#", + 2: "*", + 3: "=3D", + 4: "-", + 5: "^", + 6: '"', + } + overline =3D level <=3D 2 + marker =3D markers[level] + + self.ensure_blank_line() + # This credits all 2 or 3 lines to the single source line. + if overline: + self.add_line(marker * len(heading), info) + self.add_line(heading, info) + self.add_line(marker * len(heading), info) + self.ensure_blank_line() + + # Eat blank line(s) and advance info + trimmed =3D text.lstrip("\n") + text =3D trimmed + info =3D info.next_line(len(text) - len(trimmed) + 1) + + self.add_lines(text, info) + self.ensure_blank_line() + =20 # Disable black auto-formatter until re-enabled: # fmt: off --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797239; cv=none; d=zohomail.com; s=zohoarc; b=DzIPxQzoFfrAfcOXSsoMawoB1JybsS2+7Xeq8/hNbgcEbIBz0k72PAArK4d4E/7xXEd+fZTemPBz/eWTQKPkHf4D8DHSAVi2r37eGVWiBlVz3LNZLTai3gNmgzk5zhKj477COWGX4D1sUcNnhAVXL8uTzVIZVNWPtySqjecgPaU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797239; 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=ifDmYjcDkcsPKK2h0FWyf0lwnkxZx0G8P2XUmvBR8Ko=; b=GxwLXJFRdGpMvCfTDNusdeNTmR2U8mVu+GC2kkhF3RMmOvg2Amulz234a/lp/35zuUGZp2NjjRZHOJ2g0kUiwF4AxIbSMz4kv1KGGTDFvlcGu+IjQTnB9PmN3HrqqJH3C4+neuonuCY8KrIcj7PwgSTTO1z3vi+D7kkPFOYthZQ= 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 1738797239275766.7283258196045; Wed, 5 Feb 2025 15:13:59 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoaU-0002Ra-Am; Wed, 05 Feb 2025 18:13:42 -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 1tfoaQ-0002G0-9F for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:38 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoaO-0005hr-AH for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:38 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-373-VplHk14OM9Cq4uaHomXB-Q-1; Wed, 05 Feb 2025 18:13:25 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6EBB31800987; Wed, 5 Feb 2025 23:13:23 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A01B81800570; Wed, 5 Feb 2025 23:13:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797215; 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=ifDmYjcDkcsPKK2h0FWyf0lwnkxZx0G8P2XUmvBR8Ko=; b=Tg4+Gc9QfHKod/c6vHSLKU+8ynKodO6GQB24BLsAmcw81OAVrpaUQcJj1mWMgzYcn+u4iC qZscmuu5LwNqrxoMn4lFNzO2MU10ZEwe7y87RAlmQBgYp+vI5N/toZRubwODdz9uUGWzSt 7uHWpFzzoA97XyxYzJJgx4Q/OSYYkm4= X-MC-Unique: VplHk14OM9Cq4uaHomXB-Q-1 X-Mimecast-MFC-AGG-ID: VplHk14OM9Cq4uaHomXB-Q From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 11/42] docs/qapidoc: add preamble() method Date: Wed, 5 Feb 2025 18:11:37 -0500 Message-ID: <20250205231208.1480762-12-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797241186019000 Content-Type: text/plain; charset="utf-8" This method adds the options/preamble to each definition block. Notably, :since: and :ifcond: are added, as are any "special features" such as :deprecated: and :unstable:. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index c42cc3705aa..97868e5c375 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -38,7 +38,7 @@ from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.parser import QAPIDoc -from qapi.schema import QAPISchema +from qapi.schema import QAPISchema, QAPISchemaEntity from qapi.source import QAPISourceInfo =20 from sphinx import addnodes @@ -125,6 +125,36 @@ def ensure_blank_line(self) -> None: # +2: correct for zero/one index, then increment by one. self.add_line_raw("", fname, line + 2) =20 + # Transmogrification helpers + + def preamble(self, ent: QAPISchemaEntity) -> None: + """ + Generate option lines for qapi entity directives. + """ + if ent.doc and ent.doc.since: + assert ent.doc.since.kind =3D=3D QAPIDoc.Kind.SINCE + # Generated from the entity's docblock; info location is exact. + self.add_line(f":since: {ent.doc.since.text}", ent.doc.since.i= nfo) + + if ent.ifcond.is_present(): + doc =3D ent.ifcond.docgen() + # Generated from entity definition; info location is approxima= te. + self.add_line(f":ifcond: {doc}", ent.info) + + # Hoist special features such as :deprecated: and :unstable: + # into the options block for the entity. If, in the future, new + # special features are added, qapi-domain will chirp about + # unrecognized options and fail until they are handled in + # qapi-domain. + for feat in ent.features: + if feat.is_special(): + # FIXME: handle ifcond if present. How to display that + # information is TBD. + # Generated from entity def; info location is approximate. + self.add_line(f":{feat.name}:", feat.info) + + self.ensure_blank_line() + # Transmogrification core methods =20 def visit_module(self, path: str) -> None: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797409; cv=none; d=zohomail.com; s=zohoarc; b=ToQOl/6oDDysB6Ea6oPxbwZlAWITd0Sdy7z19AmooP7Cxx6fzg2UZoBTTTfD/BDTZ2862XVgWxGMFfEtr87b5vNw6OIpzSnUeSNpn/p8MUJVvgI3vZYc+uEGVZIwEtDZoG6A0bQ6wHV2kVvLsdx+jiRKU8dI/ZoP+q6pg6YdmAA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797409; 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=Km7i96KWs439e6Zq2JXBxnL7v+dz38hHKUKhX1ZoZRY=; b=Rd6eJxsgYV/xx1Il5Co7Qwmi+9GjANsmpN5eweLvMZf95bosUcTrGZcUv6G5DoUwbVcSfRJrYItQTt4k3eqI5nwZYJf1Fv66FYjEOrWWMs++tY559jfi812wFToK9RxGgh39zNPxFMSLyGhri+YIlGCZGdchpfZMlEsumTp1NZ4= 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 1738797409725577.3372498287171; Wed, 5 Feb 2025 15:16:49 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoaT-0002OL-3m; Wed, 05 Feb 2025 18:13:41 -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 1tfoaQ-0002FR-6c for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:38 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoaO-0005hl-E5 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:37 -0500 Received: from mx-prod-mc-01.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-475-v8OLf7giPzmcGuz9OCFrUQ-1; Wed, 05 Feb 2025 18:13:31 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E435C195608E; Wed, 5 Feb 2025 23:13:29 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B89BB1800265; Wed, 5 Feb 2025 23:13:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797214; 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=Km7i96KWs439e6Zq2JXBxnL7v+dz38hHKUKhX1ZoZRY=; b=WjsHuKD3+P05ubeQBo8SDnvPTfs6nBrYmY2mX+4zDx/DUgjxtvgS77h88sG85R8MwVGx5b eX6GlgBMI/HXbB5HD27WLYlRfWvTJbitjprLM2Mx+AUlbY5iM6MKVYH82WGMfAbu32SMu7 31Or79sKp9wvU/hYqBDIrzZ8t0BSuPA= X-MC-Unique: v8OLf7giPzmcGuz9OCFrUQ-1 X-Mimecast-MFC-AGG-ID: v8OLf7giPzmcGuz9OCFrUQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 12/42] docs/qapidoc: add visit_paragraph() method Date: Wed, 5 Feb 2025 18:11:38 -0500 Message-ID: <20250205231208.1480762-13-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797412080019100 Content-Type: text/plain; charset="utf-8" This transforms "formerly known as untagged sections" into our pure intermediate rST format. These sections are already pure rST, so this method doesn't do a whole lot except ensure appropriate newlines. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 97868e5c375..4b4cd6359e0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -127,6 +127,15 @@ def ensure_blank_line(self) -> None: =20 # Transmogrification helpers =20 + def visit_paragraph(self, section: QAPIDoc.Section) -> None: + # Squelch empty paragraphs. + if not section.text: + return + + self.ensure_blank_line() + self.add_lines(section.text, section.info) + self.ensure_blank_line() + def preamble(self, ent: QAPISchemaEntity) -> None: """ Generate option lines for qapi entity directives. --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797284; cv=none; d=zohomail.com; s=zohoarc; b=JBuqrk2ziMDAgxYxvdOd1kvDwKEpnUoVsXU37JFQ5gk7oG5YoBZFqEKmBBz4zbECZeV2Q4yzuEyaVuzjOpbVRQVHsp4iDiyV1DvxCI4HRKEyl/CIP+CY52PmkZWV9+oQjFxkdiO4nI8WJUAKP1H38elONhyKe5NhUX4sHy4bjqw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797284; 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=1dB+llB2AF47wo3EQYGNNFoz2UqpSBbz5p6oNBFLlXM=; b=TM35+viMUrwpIInY2tB7l5tMECGEv+Cc+050VBRmuROW+ga0QIne3+W/9zCYNpLOx9Z1xNCE8WCfBLkQ6Mg3c2x/yFGrwLY+1OPxkaNh/omj95sSMProMYgnzSWadvtark6t4ghXezPoIHbFLR3zFCvFf8gflQ55rU+WRxo3PwU= 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 1738797284187443.93059384205617; Wed, 5 Feb 2025 15:14:44 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoaX-0002sC-Ni; Wed, 05 Feb 2025 18:13:45 -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 1tfoaU-0002Zg-Iv for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:42 -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 1tfoaS-0005iR-Pz for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:42 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-460-RUK5um5iMkSTSEJHfx8hFQ-1; Wed, 05 Feb 2025 18:13:38 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A97BE1800872; Wed, 5 Feb 2025 23:13:36 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 813161800570; Wed, 5 Feb 2025 23:13:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797220; 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=1dB+llB2AF47wo3EQYGNNFoz2UqpSBbz5p6oNBFLlXM=; b=V8zDp08MQ0V5seh6qEkj/1pwDDUmrleVkgHB7yC3d9uBl3ka70pBpfBNAuXpUdVVlBH/Ty AHNe4OxSJk0fCt6PjCG6EbKEgab1qQu5+7u4Yr5Z3TPK1mnLThI4mT2hIgxN5Yz6YoGmaj NpSRlde8v6swgXIRmanTCAt2wEezWVE= X-MC-Unique: RUK5um5iMkSTSEJHfx8hFQ-1 X-Mimecast-MFC-AGG-ID: RUK5um5iMkSTSEJHfx8hFQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 13/42] docs/qapidoc: add visit_errors() method Date: Wed, 5 Feb 2025 18:11:39 -0500 Message-ID: <20250205231208.1480762-14-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797285859019100 Content-Type: text/plain; charset="utf-8" Notably, this method does not currently address the formatting issues present with the "errors" section in QAPIDoc and just vomits the text verbatim into the rST doc, with somewhat inconsistent results. To be addressed in a future revision. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 4b4cd6359e0..64d13565c60 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -136,6 +136,12 @@ def visit_paragraph(self, section: QAPIDoc.Section) ->= None: self.add_lines(section.text, section.info) self.ensure_blank_line() =20 + def visit_errors(self, section: QAPIDoc.Section) -> None: + # FIXME: the formatting for errors may be inconsistent and may + # or may not require different newline placement to ensure + # proper rendering as a nested list. + self.add_lines(f":error:\n{section.text}", section.info) + def preamble(self, ent: QAPISchemaEntity) -> None: """ Generate option lines for qapi entity directives. --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797337; cv=none; d=zohomail.com; s=zohoarc; b=dJwqx4k8NK4oqVVP6h7bKt+20NuuwOa2DwECl8UVb0MIJ0dSCafW6sRQ2bvX68Y/1+h8hDh+gUm1OuOL9ZT/nfAfFnKZObWvogU4iz/oY3RGfKH7zjbOhVLRBee28NnTMRW8Q+uwrKYXwNeEgMStHSFl/NomKBd/YbACZaJmNe0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797337; 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=Z5wipIxDb85GU0G4sL9WlGGn8uQ6+KchqN4BpZ1ZF7U=; b=AuXPmtKU5cB13FwhI3q2VFu2dYLKFGlkayu+ONLZF/GH2ubJSUH+h4JIw53S2r0tBdSM247Aw4G1VisyAZJZSNxtTlGxbC/o9bnwgEaM+hLbnvfdEcqrvGiGsxe78H7cctCYPjZXkhDU9nREc2/gja0Y55h3P+Z/R9EqSBJz0x8= 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 1738797337671777.7077226323955; Wed, 5 Feb 2025 15:15:37 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoae-0003Ly-Nl; Wed, 05 Feb 2025 18:13:52 -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 1tfoac-0003G0-2n for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:50 -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 1tfoaa-0005j7-Bd for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:49 -0500 Received: from mx-prod-mc-03.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-140-_2s7T-asPJ-9dzIFVpgsAQ-1; Wed, 05 Feb 2025 18:13:44 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B78F21956046; Wed, 5 Feb 2025 23:13:41 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 42BF41800570; Wed, 5 Feb 2025 23:13:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797227; 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=Z5wipIxDb85GU0G4sL9WlGGn8uQ6+KchqN4BpZ1ZF7U=; b=TmV8z4oCCcJxngjtW4z/oCtVka3cIaThOrkgTJq3QikX2TlE/bw0XAsz0RUxxs1pAEd/aG qfnBqSeoulNtKV+BNSxQDekbsOHgUM0aABUCIE69+cmmXmaAIA+HGA1eiaVIaxqd0DBtdn OkWNZ7IoeZb3qKTW/UuNHW8a5JZHkAM= X-MC-Unique: _2s7T-asPJ-9dzIFVpgsAQ-1 X-Mimecast-MFC-AGG-ID: _2s7T-asPJ-9dzIFVpgsAQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 14/42] docs/qapidoc: add format_type() method Date: Wed, 5 Feb 2025 18:11:40 -0500 Message-ID: <20250205231208.1480762-15-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797339543019000 Content-Type: text/plain; charset="utf-8" This method is responsible for generating a type name for a given member with the correct annotations for the QAPI domain. Features and enums do not *have* types, so they return None. Everything else returns the type name with a "?" suffix if that type is optional, and ensconced in [brackets] if it's an array type. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 64d13565c60..b1eaac6e215 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -30,7 +30,7 @@ import re import sys import textwrap -from typing import List +from typing import List, Optional =20 from docutils import nodes from docutils.parsers.rst import Directive, directives @@ -38,7 +38,14 @@ from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.parser import QAPIDoc -from qapi.schema import QAPISchema, QAPISchemaEntity +from qapi.schema import ( + QAPISchema, + QAPISchemaArrayType, + QAPISchemaEntity, + QAPISchemaEnumMember, + QAPISchemaFeature, + QAPISchemaObjectTypeMember, +) from qapi.source import QAPISourceInfo =20 from sphinx import addnodes @@ -125,6 +132,25 @@ def ensure_blank_line(self) -> None: # +2: correct for zero/one index, then increment by one. self.add_line_raw("", fname, line + 2) =20 + def format_type(self, ent) -> Optional[str]: + if isinstance(ent, (QAPISchemaEnumMember, QAPISchemaFeature)): + return None + + qapi_type =3D ent + optional =3D False + if isinstance(ent, QAPISchemaObjectTypeMember): + qapi_type =3D ent.type + optional =3D ent.optional + + if isinstance(qapi_type, QAPISchemaArrayType): + ret =3D f"[{qapi_type.element_type.doc_type()}]" + else: + ret =3D qapi_type.doc_type() + if optional: + ret +=3D "?" + + return ret + # Transmogrification helpers =20 def visit_paragraph(self, section: QAPIDoc.Section) -> None: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797291; cv=none; d=zohomail.com; s=zohoarc; b=IFW23Deu9HgEbrqANovH5MhxTC+Rnzv5n96F1WvfoCZYgRexH/WhSvAVAaTdSRISGntW2UqdcJZSqCRZEwEVANYbj4VBz0UvQjWnPKBwkwzteaoA2Rha/WY4+hHgo/XqvDxW+WoKN/4x2Ia8v8hbkEUHX5RgUBZhxVIV7k/9fQk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797291; 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=m0QbqVVziYYlhKxw0U7Uuz2w5aKlr2kUtddAIT6yRpM=; b=CkkwplaCnFSz3Xhsb/tLRZF27n+Cge+K3LfrSsAD0mq+YqNrtn3uR3jP+zDM6tEkasafDj1HrEx5ugE936eskEUsBoqA7ru6cxRn4z/hzB/H7A2bpCTmrW8qLo5mLk3Vl6+OGEs5fwSaZzE9AAfRGOyf+5bygNR31h+RbAeLM6I= 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 1738797291110924.8712028068745; Wed, 5 Feb 2025 15:14:51 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoai-0003dS-U0; Wed, 05 Feb 2025 18:13:57 -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 1tfoaf-0003OO-20 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:53 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoad-0005jW-HS for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:52 -0500 Received: from mx-prod-mc-03.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-663-v8pyF7p_MOakR3YJWJmCxA-1; Wed, 05 Feb 2025 18:13:47 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1DC261955F17; Wed, 5 Feb 2025 23:13:46 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1C0221800267; Wed, 5 Feb 2025 23:13:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797230; 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=m0QbqVVziYYlhKxw0U7Uuz2w5aKlr2kUtddAIT6yRpM=; b=SAc3LP6rUgjyaTOm81mHf/zFl1xvg5xzSfUvHFVUaO3AU5PIlmQe6RDngLHKEqbGBZjIt7 aRnEEcT20ecCsjGwsXXKZODK+b3vNuEOQx9w/dpljiFVox0817FZAnIA1v5jmITsPU/OP6 nIuRDCTl/PPROaB25seIBwzgDXF2QRY= X-MC-Unique: v8pyF7p_MOakR3YJWJmCxA-1 X-Mimecast-MFC-AGG-ID: v8pyF7p_MOakR3YJWJmCxA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 15/42] docs/qapidoc: add add_field() and generate_field() helper methods Date: Wed, 5 Feb 2025 18:11:41 -0500 Message-ID: <20250205231208.1480762-16-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797291887019100 Content-Type: text/plain; charset="utf-8" These are simple rST generation methods that assist in getting the types and formatting correct for a field list entry. add_field() is a more raw, direct call while generate_field() is intended to be used for generating the correct field from a member object. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b1eaac6e215..6c0e7b6004c 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -44,6 +44,7 @@ QAPISchemaEntity, QAPISchemaEnumMember, QAPISchemaFeature, + QAPISchemaMember, QAPISchemaObjectTypeMember, ) from qapi.source import QAPISourceInfo @@ -132,6 +133,20 @@ def ensure_blank_line(self) -> None: # +2: correct for zero/one index, then increment by one. self.add_line_raw("", fname, line + 2) =20 + def add_field( + self, + kind: str, + name: str, + body: str, + info: QAPISourceInfo, + typ: Optional[str] =3D None, + ) -> None: + if typ: + text =3D f":{kind} {typ} {name}: {body}" + else: + text =3D f":{kind} {name}: {body}" + self.add_lines(text, info) + def format_type(self, ent) -> Optional[str]: if isinstance(ent, (QAPISchemaEnumMember, QAPISchemaFeature)): return None @@ -151,6 +166,16 @@ def format_type(self, ent) -> Optional[str]: =20 return ret =20 + def generate_field( + self, + kind: str, + member: QAPISchemaMember, + body: str, + info: QAPISourceInfo, + ) -> None: + typ =3D self.format_type(member) + self.add_field(kind, member.name, body, info, typ) + # Transmogrification helpers =20 def visit_paragraph(self, section: QAPIDoc.Section) -> None: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797512; cv=none; d=zohomail.com; s=zohoarc; b=L2ZXLPXtffjZ8QBYrDniKxfNoEvdZdc3eAZDXOlLcx92Fhm+xYxetEI8+1vQtp5UJsuAomWYyhNHGRP2BTP+J9PIjEzanhWJHJai7eIMBZjqHkEEfQgfEkODkVDtMRJSwVH6L8/B2SWSASl3FPAYheHdaHGFzjLW/5oOv8elX9Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797512; 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=Zw2+xsvYZymW8Ga617RcEmXEQuj7aGmhJlHM7fsUBBo=; b=QkDBYz8bgGdGX/ZVWyBC1bdgsqLhfvLFC8HYJemV3gIy+1tiiuW/MKxgYd4QTmi9tb4vwaC5Q+jYKk7qjq2Ml8XA5YBQ3UJKgdIJQN6cYDCDvPwf+c4sJ3pVfBzh34RKh6cuthtuwSa2TNqCsjXKYcC1fSRz6nFRneLueUOHq6w= 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 173879751213791.56010533436586; Wed, 5 Feb 2025 15:18:32 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfob5-0004Uz-Hp; Wed, 05 Feb 2025 18:14:19 -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 1tfoal-0003xF-Rz for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:02 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfoak-0005kZ-6Y for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:13:59 -0500 Received: from mx-prod-mc-04.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-115-ug25Yk_qMIusnsv56ETHEA-1; Wed, 05 Feb 2025 18:13:53 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0FC561955D6F; Wed, 5 Feb 2025 23:13:52 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7A3621800570; Wed, 5 Feb 2025 23:13:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797237; 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=Zw2+xsvYZymW8Ga617RcEmXEQuj7aGmhJlHM7fsUBBo=; b=MPrExWXabZgPKMIR8XG7BGsvkdhIf1oWPEm6V0Xc9X//OcKRkm5KdGNooj6lb21900+0qT X+d1Ut7y4miJnwXyks4x4v3IdpRd5PxZyqBStju50zKfxObaa4d0wkiuIwMXHHkbzUJY2m c4AUoxuT6RFCuscuM3HnVVyqKAIjZJE= X-MC-Unique: ug25Yk_qMIusnsv56ETHEA-1 X-Mimecast-MFC-AGG-ID: ug25Yk_qMIusnsv56ETHEA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 16/42] docs/qapidoc: add visit_feature() method Date: Wed, 5 Feb 2025 18:11:42 -0500 Message-ID: <20250205231208.1480762-17-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797514294019000 Content-Type: text/plain; charset="utf-8" This adds a simple ":feat name: lorem ipsum ..." line to the generated rST document, so at the moment it's only for "top level" features. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6c0e7b6004c..e9af072c5a6 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -187,6 +187,15 @@ def visit_paragraph(self, section: QAPIDoc.Section) ->= None: self.add_lines(section.text, section.info) self.ensure_blank_line() =20 + def visit_feature(self, section: QAPIDoc.ArgSection) -> None: + # FIXME - ifcond for features is not handled at all yet! + # Proposal: decorate the right-hand column with some graphical + # element to indicate conditional availability? + assert section.text # Guaranteed by parser.py + assert section.member + + self.generate_field("feat", section.member, section.text, section.= info) + def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and may # or may not require different newline placement to ensure --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797410; cv=none; d=zohomail.com; s=zohoarc; b=DVfUrFxM8CefKXJ6m8r2uX0omjgWNtq3DoQta6Pw3ksUbHRsps8ptdi+JaB28IGb2vnFHxP+krdLUnyz2oX7m8tZ7kWG5ouJ3b8o+VnfQBQeE6DrHHMprdY++1PUQDlzKtHNlMWiPoay/bleAHfucG/0vqBuDR65AKftlugGr74= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797410; 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=HRpc7AwRZVi7Vg7CoI/dFhPnm3CysqVN8sNkubJQE9Y=; b=Aru91O56yqA96pL5WCY4IQvjJCgmbn45O3B+iGjURHLLd4ZyXgED9YttqrauIJAz5p5M58eAczWPuRcvSwmxK/3CIZMGgES06PBzA/OuBxpws87v53jiEuer3nbr3vCuPxWDi1ARGYCTA8ShJ2vFmHRPI9nqFRRYeHm6qLmktjQ= 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 1738797410249171.1625870198185; Wed, 5 Feb 2025 15:16:50 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobB-00051Y-7e; Wed, 05 Feb 2025 18:14:25 -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 1tfoap-00047M-VW for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:07 -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 1tfoao-0005kl-G6 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:03 -0500 Received: from mx-prod-mc-03.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-352-kxlXjwkzP9awaE_lNMqcAQ-1; Wed, 05 Feb 2025 18:14:00 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3090E1955F16; Wed, 5 Feb 2025 23:13:58 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 9CDA51800570; Wed, 5 Feb 2025 23:13:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797241; 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=HRpc7AwRZVi7Vg7CoI/dFhPnm3CysqVN8sNkubJQE9Y=; b=JEfF+d7nQlQmZ5L0ilXrilfaLC2RiB5pj5kx0nLQ4cekdglPbRAGHhcxyvLJlstUniSUlc R9j+pb5tH0iL0fnnQZnoMcZ4DXUsFTylYfKudcRXJtaNcxtviTB1LCPBPW4NpPUpTMNJCl Vk7DAyCl03WKpFCKBexQXMXrvCUegpM= X-MC-Unique: kxlXjwkzP9awaE_lNMqcAQ-1 X-Mimecast-MFC-AGG-ID: kxlXjwkzP9awaE_lNMqcAQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 17/42] docs/qapidoc: prepare to record entity being transmogrified Date: Wed, 5 Feb 2025 18:11:43 -0500 Message-ID: <20250205231208.1480762-18-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797411763019000 Content-Type: text/plain; charset="utf-8" Prepare to keep a record of which entity we're working on documenting for the purposes of being able to change certain generative features conditionally and create stronger assertions. If you find yourself asking: "Wait, but where does the current entity actually get recorded?!", you're right! That part comes with the visit_entity() implementation, which gets added later. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index e9af072c5a6..a4dbfa3b3dd 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -74,9 +74,15 @@ def dedent(text: str) -> str: =20 class Transmogrifier: def __init__(self, schema): + self._curr_ent =3D None self._result =3D StringList() self.indent =3D 0 =20 + @property + def entity(self) -> QAPISchemaEntity: + assert self._curr_ent is not None + return self._curr_ent + # General-purpose rST generation functions =20 def get_indent(self) -> str: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797447; cv=none; d=zohomail.com; s=zohoarc; b=aMcZXS2C/LALuAjsWgCg7Jbfk3FnvrhxBKsk4iTGltVOGxCyeoPnR3cCJg8yq8fpIKEccnXLUCVL9WWxRM1PSumCgzsRvn/Ijq+QZrftKOLLJhAS6o9YdAgsSCTUZJd1LssCdhR73FboCldWIwJkaRtIue5tDjdAqFXFmI/u/J8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797447; 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=MB01enPJx5x1zjoGQFth+B6JXUSxP2JjqwSrUVhEKq8=; b=c36NBm2+QxepOEin3YeGq6UPz4N6B+Ed1Gh2QcaMJ7nL+llliHKmJhUMs4m/I5Xoj5SQsV4I8qJKxxOjW3R3Bj+/V2y0LcETveuXLcILK98dauB0CQjlrvNbluJFlOLWf4bZol9ruFATeMuMMdH0k1STnnTP7Zazr100v/27h7o= 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 1738797447481574.2705219355071; Wed, 5 Feb 2025 15:17:27 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfob9-0004l1-2D; Wed, 05 Feb 2025 18:14:23 -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 1tfoaw-0004Ed-6R for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:15 -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 1tfoau-0005lW-Kk for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:09 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-662-40Smxc9yN-aR00eu2sUayw-1; Wed, 05 Feb 2025 18:14:06 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 957111800872; Wed, 5 Feb 2025 23:14:04 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 75D091800871; Wed, 5 Feb 2025 23:13:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797247; 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=MB01enPJx5x1zjoGQFth+B6JXUSxP2JjqwSrUVhEKq8=; b=exCa+r9hh+Uwl/FR89q01z7fC891cix2FASunmt/k+48vOGmSTPPeP09hTbfIedeP7okpj ads6KSRp+NThFHoBoKVTfDyj8wflDFiUopI8xELG96Flq9GGgRsbhQURfUjTBIQs21hU2P KB7OKEjclTwFXNZ2pT/XNR+E+SzCw1w= X-MC-Unique: 40Smxc9yN-aR00eu2sUayw-1 X-Mimecast-MFC-AGG-ID: 40Smxc9yN-aR00eu2sUayw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 18/42] docs/qapidoc: add visit_returns() method Date: Wed, 5 Feb 2025 18:11:44 -0500 Message-ID: <20250205231208.1480762-19-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797447878019000 Content-Type: text/plain; charset="utf-8" Generates :returns: fields for explicit returns statements. Note that this does not presently handle undocumented returns, which is handled in a later commit. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index a4dbfa3b3dd..cbc62eb5084 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -41,6 +41,7 @@ from qapi.schema import ( QAPISchema, QAPISchemaArrayType, + QAPISchemaCommand, QAPISchemaEntity, QAPISchemaEnumMember, QAPISchemaFeature, @@ -202,6 +203,19 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -= > None: =20 self.generate_field("feat", section.member, section.text, section.= info) =20 + def visit_returns(self, section: QAPIDoc.Section) -> None: + assert isinstance(self.entity, QAPISchemaCommand) + rtype =3D self.entity.ret_type + # q_empty can produce None, but we won't be documenting anything + # without an explicit return statement in the doc block, and we + # should not have any such explicit statements when there is no + # return value. + assert rtype + + typ =3D self.format_type(rtype) + assert section.text # We don't expect empty returns sections. + self.add_field("returns", typ, section.text, section.info) + def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and may # or may not require different newline placement to ensure --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797335; cv=none; d=zohomail.com; s=zohoarc; b=GZDwu9Gk/jQNpq5+E3OazTgwr2JaxPMh6Lp3krCUyGnTzElpwgDNaj3QK8UXIkugpzhnTxGozEg+GCyPxX/M8H+X0jH56pCeQvZEvzkuGy1flnt3HfGf4gsHn80ZRBV9FvhnZTRqJ/cShPvw/MRJmGB2aluQaR1LXUIbdLUzYhQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797335; 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=Y3so7sjMVhMRbBG93ZOIT+wc4861dMaNY5TLcWMYjjQ=; b=Y1m9q5ssM60PgoiVb7xKt2blRrD+XQRgdcZ3RDMj/mAdQ64w3ScuFmzG1/qSMqbTubJxdyzB6a1ZAMDSkUg9exdHptuGxVCqNIYFBBTJOR/ZIu2JlQvLj9IpSwqPLDgWptTBbD6jAzRATPlGXFKrGMntXGWe57TcSUekUPp3FGk= 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 1738797335557454.9427258184478; Wed, 5 Feb 2025 15:15:35 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobE-0005OD-Cu; Wed, 05 Feb 2025 18:14:28 -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 1tfob5-0004Wh-AX for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:19 -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 1tfob3-0005lz-L8 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:19 -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-446-Xq75XvX1MYOWMUDvs0LupA-1; Wed, 05 Feb 2025 18:14:13 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 ED7881956088; Wed, 5 Feb 2025 23:14:10 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2097E1800267; Wed, 5 Feb 2025 23:14:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797257; 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=Y3so7sjMVhMRbBG93ZOIT+wc4861dMaNY5TLcWMYjjQ=; b=JRFXXNF/uC1iofLAdJB/rTQ4k7+USfM5FHf5BymIGjjLiaR0ZZDVMfu5kS6V0B9ts0jhW5 Rx13I87snJ4m4LpSHIiay+9a6UKon+NXywsy9/b9Q4Z9dIBUsV93otymAVPwzhPEim190M Rj/GlY6xNVyErfNXXt7MsrB88Af88PM= X-MC-Unique: Xq75XvX1MYOWMUDvs0LupA-1 X-Mimecast-MFC-AGG-ID: Xq75XvX1MYOWMUDvs0LupA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 19/42] docs/qapidoc: add visit_member() method Date: Wed, 5 Feb 2025 18:11:45 -0500 Message-ID: <20250205231208.1480762-20-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797337846019100 Content-Type: text/plain; charset="utf-8" This method is used for generating the "members" of a wide variety of things, including structs, unions, enums, alternates, etc. The field name it uses to do so is dependent on the type of entity the "member" belongs to. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index cbc62eb5084..5f00615ae32 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -74,6 +74,16 @@ def dedent(text: str) -> str: =20 =20 class Transmogrifier: + # Field names used for different entity types: + field_types =3D { + "enum": "value", + "struct": "memb", + "union": "memb", + "event": "memb", + "command": "arg", + "alternate": "choice", + } + def __init__(self, schema): self._curr_ent =3D None self._result =3D StringList() @@ -84,6 +94,10 @@ def entity(self) -> QAPISchemaEntity: assert self._curr_ent is not None return self._curr_ent =20 + @property + def member_field_type(self) -> str: + return self.field_types[self.entity.meta] + # General-purpose rST generation functions =20 def get_indent(self) -> str: @@ -194,6 +208,19 @@ def visit_paragraph(self, section: QAPIDoc.Section) ->= None: self.add_lines(section.text, section.info) self.ensure_blank_line() =20 + def visit_member(self, section: QAPIDoc.ArgSection) -> None: + # TODO: ifcond for members + # TODO?: features for members (documented at entity-level, + # but sometimes defined per-member. Should we add such + # information to member descriptions when we can?) + assert section.text + self.generate_field( + self.member_field_type, + section.member, + section.text, + section.info, + ) + def visit_feature(self, section: QAPIDoc.ArgSection) -> None: # FIXME - ifcond for features is not handled at all yet! # Proposal: decorate the right-hand column with some graphical --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797439; cv=none; d=zohomail.com; s=zohoarc; b=dmzEx1D7jbS2bsHXzjEylfBHrKsM9oPqAUkyU9Z5g+EfOwm7/Cr1AiNrvH/goMPvqN3VRPFfKmGHuzyFk0GToH3ZjrehWoSmtjupt0gKKr7WUmOHzEGQJFlNIsa7l8Ka2vHLv9BvM24jHNj0hpimNLLJlDmUCH/INXv5v+Nd/2g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797439; 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=WFwRHJBuGsYcGLiNHZZ8biZPsF+DncQMI1zu0iuDMjs=; b=ju6I3aGjQbStj3llMXKCMH5MVBqGIwsfQI+PkaiUJkuK4OsXuqHuUi/Lp7ljl+rXKKvhswwzs0dq0AfWRoNXypAdyKOpSC7kLBhOe39PfxZuFD6IfeEtN4bqMi1CK3NDnQB951EDklF9V6/cdM2Jx6nZ6wIH03JcDlatc1i7oWc= 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 1738797439881732.8939184958015; Wed, 5 Feb 2025 15:17:19 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobL-00067Q-7I; Wed, 05 Feb 2025 18:14:35 -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 1tfobA-00050X-Dq for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:24 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfob8-0005mU-NZ for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:24 -0500 Received: from mx-prod-mc-02.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-567-QWGW0Qc-Ol6V1U0Pz1yYeA-1; Wed, 05 Feb 2025 18:14:18 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2E0F01956089; Wed, 5 Feb 2025 23:14:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 71FD41800570; Wed, 5 Feb 2025 23:14:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797262; 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=WFwRHJBuGsYcGLiNHZZ8biZPsF+DncQMI1zu0iuDMjs=; b=FYe5go9YianNCRiQjp6qwLs565HLJUiCJ+/xggM/QLNGkpL5NWE/F0KqiJXwcN7fm4bTfl Nxrd5AVQZUsU3OkApCNk6z66/coYgllEsl/rk4MGRO3GVnTdDJ/kANiH6syLhLIAr0Ht3P ntpMAKxbWw9DmzHLUVw0Fpz9QWKtSqE= X-MC-Unique: QWGW0Qc-Ol6V1U0Pz1yYeA-1 X-Mimecast-MFC-AGG-ID: QWGW0Qc-Ol6V1U0Pz1yYeA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 20/42] docs/qapidoc: add visit_sections() method Date: Wed, 5 Feb 2025 18:11:46 -0500 Message-ID: <20250205231208.1480762-21-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797442183019100 Content-Type: text/plain; charset="utf-8" Implement the actual main dispatch method that processes and handles the list of doc sections for a given QAPI entity. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5f00615ae32..73076a7d6ae 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -277,6 +277,29 @@ def preamble(self, ent: QAPISchemaEntity) -> None: =20 self.ensure_blank_line() =20 + def visit_sections(self, ent: QAPISchemaEntity) -> None: + sections =3D ent.doc.all_sections if ent.doc else [] + + # Add sections *in the order they are documented*: + for section in sections: + if section.kind =3D=3D QAPIDoc.Kind.PLAIN: + self.visit_paragraph(section) + elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: + self.visit_member(section) + elif section.kind =3D=3D QAPIDoc.Kind.FEATURE: + self.visit_feature(section) + elif section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO): + # Since is handled in preamble, TODO is skipped intentiona= lly. + pass + elif section.kind =3D=3D QAPIDoc.Kind.RETURNS: + self.visit_returns(section) + elif section.kind =3D=3D QAPIDoc.Kind.ERRORS: + self.visit_errors(section) + else: + assert False + + self.ensure_blank_line() + # Transmogrification core methods =20 def visit_module(self, path: str) -> None: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797566; cv=none; d=zohomail.com; s=zohoarc; b=Qzz59K3S+43Al1zovRPQu58hciPZbtxk/mS+cvcVt/Jh/HB07y/lwMcZd3kQAbbBCTbOD1QMDhNlRP4vYb0sDA4/aF9/jL5RCAcrYj0tYu5ZgeSla9Io+qJJKLSLwAyfXhRAtepmbwOX0FkjSOX+OV4M4hiJjjs5fKfctLzIj4M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797566; 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=1c7ePKtMBm+bNj+fmk6m4eAlibusxGj28DxoqbMpHG8=; b=QsNjyW3xqHQe86NP3S3kackbowvwXFqe/VoTnkEqMwAABJjVIqL0FXRzewqvh9oH3744xIbBumj7mGDXPGOFlOQizeYIRLS7rCqRhQe4wqiN62M4sI3EilbZa8L71dMgS1Sd/XQK5gp80Zjd8XGlN2Hcpx5YF+7gkVaBt1wlsvE= 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 1738797566956841.1811515765266; Wed, 5 Feb 2025 15:19:26 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobH-0005pl-Il; Wed, 05 Feb 2025 18:14:31 -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 1tfobF-0005ZZ-1u for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:29 -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 1tfobD-0005n2-E4 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:28 -0500 Received: from mx-prod-mc-03.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-50-v70MPH4KPOeEXtJZ6Lsqdg-1; Wed, 05 Feb 2025 18:14:24 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B11531955E89; Wed, 5 Feb 2025 23:14:22 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7FF301800570; Wed, 5 Feb 2025 23:14:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797266; 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=1c7ePKtMBm+bNj+fmk6m4eAlibusxGj28DxoqbMpHG8=; b=XDurbwQmikLBZ/8Uq7/ZLTfM9gdcDAOFQ4/ooldFbC89mvEisRDqHBzuveCpEUYHWQrZQc f7FFBMxtYdxDpo8/TagMOVokkW2GjUpcAUGgimj9JJn09yWsLwSyLWN2XuiiHJzuavBtEu xwrsr+GS6dSGIlt5Ntd2YVHCxkpM2S4= X-MC-Unique: v70MPH4KPOeEXtJZ6Lsqdg-1 X-Mimecast-MFC-AGG-ID: v70MPH4KPOeEXtJZ6Lsqdg From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 21/42] docs/qapidoc: add visit_entity() Date: Wed, 5 Feb 2025 18:11:47 -0500 Message-ID: <20250205231208.1480762-22-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797568532019100 Content-Type: text/plain; charset="utf-8" Finally, the core entry method for a qapi entity. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 73076a7d6ae..a2fc8d25ff7 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -355,6 +355,19 @@ def visit_freeform(self, doc) -> None: self.add_lines(text, info) self.ensure_blank_line() =20 + def visit_entity(self, ent): + assert ent is not None + + try: + self._curr_ent =3D ent + # This line gets credited to the start of the /definition/. + self.add_line(f".. qapi:{ent.meta}:: {ent.name}", ent.info) + with self.indented(): + self.preamble(ent) + self.visit_sections(ent) + finally: + self._curr_ent =3D None + =20 # Disable black auto-formatter until re-enabled: # fmt: off --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797485; cv=none; d=zohomail.com; s=zohoarc; b=PaSeeg7/antp6yiuxg00hbVqxro8HobjLV6c1eZOIIA5QPgZYNUPt9lYQDUwbTaFfj7n6dNV3OHzNZP+5725fTkp72Fmd09JibrWBtJ5iPc0Xm8BifRk9wQ3j5OwomxmcWEHJmVXn/Rn6v9VQ0HTUiqt4BrNRq6kY+Hokj62tV0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797485; 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=278Eb9ocdeu0z89TjrvD1X9u33jicusB2e0favNu2BQ=; b=Qg+ZvyzJXfTm+PJfpF3UtEbL5/3XV9zHo1VPXlid39dic2X2ezyv3KsDhUejgDyDoib7Aw28PgghKr5SX4BxwVMhgNk5ae5qzw+TS+uJUFsPoh9TggneIiHWDM0smfNQ+UVoZIb+5/IgVYvKvlQ8EQUnnaTLQ+c2eF2GvQszr0U= 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 1738797485412109.73260152208627; Wed, 5 Feb 2025 15:18:05 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobP-0006kO-Nt; Wed, 05 Feb 2025 18:14:39 -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 1tfobM-0006Nd-K1 for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:36 -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 1tfobK-0005nv-TW for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:36 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-396-JIsQf76iOFaWmyWpJqnHuA-1; Wed, 05 Feb 2025 18:14:31 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 786761800981; Wed, 5 Feb 2025 23:14:29 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 59A571800570; Wed, 5 Feb 2025 23:14:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797274; 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=278Eb9ocdeu0z89TjrvD1X9u33jicusB2e0favNu2BQ=; b=XNIEUlfVGUe5aBLRNJBQGyN5AdOWZ+QZhv4vzc68MefVj9fjAoli0iuykQGRuAq4IfKq3F +yXiuw3lx0jHBw08rIF1rxVIbjBlFLnH8HxUJwEJG4XibU3WG/z7XO2fkrOfkW5ASKrKpU V9guq+Kxr8rYHBygB45mD+qIyXBxC+Y= X-MC-Unique: JIsQf76iOFaWmyWpJqnHuA-1 X-Mimecast-MFC-AGG-ID: JIsQf76iOFaWmyWpJqnHuA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 22/42] docs/qapidoc: implement transmogrify() method Date: Wed, 5 Feb 2025 18:11:48 -0500 Message-ID: <20250205231208.1480762-23-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797486049019000 Content-Type: text/plain; charset="utf-8" This is the true top-level processor for the new transmogrifier; responsible both for generating the intermediate rST and then running the nested parse on that generated document to produce the final docutils tree that is then - very finally - postprocessed by sphinx for final rendering to HTML &c. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 47 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index a2fc8d25ff7..5d946a46637 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -2,6 +2,7 @@ # # QEMU qapidoc QAPI file parsing extension # +# Copyright (c) 2024 Red Hat # Copyright (c) 2020 Linaro # # This work is licensed under the terms of the GNU GPLv2 or later. @@ -53,12 +54,15 @@ from sphinx import addnodes from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError +from sphinx.util import logging from sphinx.util.docutils import switch_source_input from sphinx.util.nodes import nested_parse_with_titles =20 =20 __version__ =3D "1.0" =20 +logger =3D logging.getLogger(__name__) + =20 def dedent(text: str) -> str: # Adjust indentation to make description text parse as paragraph. @@ -89,6 +93,10 @@ def __init__(self, schema): self._result =3D StringList() self.indent =3D 0 =20 + @property + def result(self) -> StringList: + return self._result + @property def entity(self) -> QAPISchemaEntity: assert self._curr_ent is not None @@ -823,7 +831,43 @@ def new_serialno(self): return "qapidoc-%d" % env.new_serialno("qapidoc") =20 def transmogrify(self, schema) -> nodes.Element: - raise NotImplementedError + logger.info("Transmogrifying QAPI to rST ...") + vis =3D Transmogrifier(schema) + modules =3D set() + + for doc in schema.docs: + module_source =3D doc.info.fname + if module_source not in modules: + vis.visit_module(module_source) + modules.add(module_source) + + if doc.symbol: + ent =3D schema.lookup_entity(doc.symbol) + assert ent + vis.visit_entity(ent) + else: + vis.visit_freeform(doc) + + logger.info("Transmogrification complete.") + + contentnode =3D nodes.section() + content =3D vis.result + titles_allowed =3D True + + logger.info("Transmogrifier running nested parse ...") + with switch_source_input(self.state, content): + if titles_allowed: + node: nodes.Element =3D nodes.section() + node.document =3D self.state.document + nested_parse_with_titles(self.state, content, contentnode) + else: + node =3D nodes.paragraph() + node.document =3D self.state.document + self.state.nested_parse(content, 0, contentnode) + logger.info("Transmogrifier's nested parse completed.") + sys.stdout.flush() + + return contentnode =20 def legacy(self, schema) -> nodes.Element: vis =3D QAPISchemaGenRSTVisitor(self) @@ -957,6 +1001,7 @@ def run(self) -> List[nodes.Node]: =20 def setup(app): """Register qapi-doc directive with Sphinx""" + app.setup_extension("qapi-domain") app.add_config_value("qapidoc_srctree", None, "env") app.add_directive("qapi-doc", QAPIDocDirective) app.add_directive("qmp-example", QMPExample) --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797394; cv=none; d=zohomail.com; s=zohoarc; b=GDT82ZvHvYp4rC+BHYvIt77P4oNPxPBcJMoF+cTaPsydBxyx+yhDXfAFxSRVz/0+2AjsBa22TULXJct+gAHlUBKq8fnYswh3n+ABLnZqYSCnT9R2tuW9t9rRLcAK7bvV0bfcstQ3cu1v9UnfV1Rl+GNtABpGpSEqgj0vYaKdpJo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797394; 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=95agMskPgnBc4AkyN44TZ2mvq+7CH/4kl3dTXY02EW8=; b=DMu/oFJMDjX8v6HTXpD0rQcW36k0/xiaREC+UAK6WA1HdPsxw8fljsE6+v2uz2P6esQ2+dgSJacdXP9h9Zo9WJambwHCSOn/IIRMxXrgLWYXdGFM/2LbHcazeE8Su+bxI6NwKweCrLeweTRQhdJ21RgeAI/19kHaSNviVPpUJgw= 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 1738797394614752.2838658045749; Wed, 5 Feb 2025 15:16:34 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobe-0007Ka-Ec; Wed, 05 Feb 2025 18:14:54 -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 1tfobU-00074Y-Bi for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:45 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfobS-0005oZ-Ha for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:44 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-501-nzikFatNNNaT-OdX2sHf0w-1; Wed, 05 Feb 2025 18:14:37 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 20137180036F; Wed, 5 Feb 2025 23:14:36 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1DED41800570; Wed, 5 Feb 2025 23:14:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797280; 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=95agMskPgnBc4AkyN44TZ2mvq+7CH/4kl3dTXY02EW8=; b=Mo1+t3qJ2QAkRTTi+Ji2oxqnNXkWt//hdzV0EeRqVk1RzaXSThs4avNSbN9lNepAU4Z/nv 14uvToNaps+MQBMY/Oh9syB9e+AgcyVeyoGXNLO4CeZOwkXWmwjVPD6KlyRzmExUJ13K1M CwFYR7d57X7Bp/85IrWs/RR1e8fkTcA= X-MC-Unique: nzikFatNNNaT-OdX2sHf0w-1 X-Mimecast-MFC-AGG-ID: nzikFatNNNaT-OdX2sHf0w From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 23/42] docs: disambiguate cross-references Date: Wed, 5 Feb 2025 18:11:49 -0500 Message-ID: <20250205231208.1480762-24-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797395886019000 Content-Type: text/plain; charset="utf-8" The next patch will engage the qapidoc transmogrifier, which creates a lot of cross-reference targets. Some of the existing targets ("migration", "qom", "replay") will become ambiguous as a result. Nail them down more explicitly to prevent ambiguous cross-reference warnings. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/devel/codebase.rst | 6 +++--- docs/glossary.rst | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/devel/codebase.rst b/docs/devel/codebase.rst index 4039875ee04..1b09953197b 100644 --- a/docs/devel/codebase.rst +++ b/docs/devel/codebase.rst @@ -23,7 +23,7 @@ Some of the main QEMU subsystems are: - `Devices` & Board models - `Documentation ` - `GDB support` -- `Migration` +- :ref:`Migration` - `Monitor` - :ref:`QOM (QEMU Object Model)` - `System mode` @@ -112,7 +112,7 @@ yet, so sometimes the source code is all you have. * `libdecnumber `_: Import of gcc library, used to implement decimal number arithmetic. * `migration `__: - `Migration framework `. + :ref:`Migration framework `. * `monitor `_: `Monitor ` implementation (HMP & QMP). * `nbd `_: @@ -193,7 +193,7 @@ yet, so sometimes the source code is all you have. - `lcitool `_: Generate dockerfiles for CI containers. - `migration `_: - Test scripts and data for `Migration framework `. + Test scripts and data for :ref:`Migration framework `. - `multiboot `_: Test multiboot functionality for x86_64/i386. - `qapi-schema `_: diff --git a/docs/glossary.rst b/docs/glossary.rst index 693d9855dd1..4fa044bfb6e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -120,7 +120,7 @@ Migration --------- =20 QEMU can save and restore the execution of a virtual machine between diffe= rent -host systems. This is provided by the `Migration framework`. +host systems. This is provided by the :ref:`Migration framework= `. =20 NBD --- @@ -212,14 +212,14 @@ machine emulator and virtualizer. QOM --- =20 -`QEMU Object Model ` is an object oriented API used to define various -devices and hardware in the QEMU codebase. +:ref:`QEMU Object Model ` is an object oriented API used to define +various devices and hardware in the QEMU codebase. =20 Record/replay ------------- =20 -`Record/replay ` is a feature of QEMU allowing to have a determini= stic -and reproducible execution of a virtual machine. +:ref:`Record/replay ` is a feature of QEMU allowing to have a +deterministic and reproducible execution of a virtual machine. =20 Rust ---- --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797522; cv=none; d=zohomail.com; s=zohoarc; b=XBf13RtomBJfOkRgBFN0023/wx+GLh8h1Ml/UkEjlV0vx4GkIVTpJayNEoagg1Vzt0FBwyHag97W05lsXbu5wpT8SdIqXqTS1ni8MAbYVCrQxbW2w8h1Gp+g1qsO82EfZmw/9xGfej/pgrz20ifn3VdaF7a/3CbW6cpu/F6Cgb4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797522; 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=74Z3rjfmLCK5MKWoQQ9msNIaheYuoK/rIVoIzOZKnX8=; b=i/B3+stJCg1Om/1ZiqsSqL3J9rz9yiBAimg7+fLL1geuFIsA1Yh2MVlQBHljWMBI3r/u2Dv/sHj8dKorOzmz3rwbmIg/OJcpM1dS+Iwb+as1GsoUoBj6jn0saJ44yOSCtktOBwsZiHaXi3b2sBNyDid1Qi7mIh9ObqCpd7Yr+ZA= 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 1738797522320116.1892457009244; Wed, 5 Feb 2025 15:18:42 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobj-0007aE-TZ; Wed, 05 Feb 2025 18:15:00 -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 1tfobY-00079w-SZ for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:50 -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 1tfobX-0005ou-3z for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:48 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-630-0Jqo_CvEOgGY7BRezMMVsA-1; Wed, 05 Feb 2025 18:14:44 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1EABA180087E; Wed, 5 Feb 2025 23:14:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 659EE1800265; Wed, 5 Feb 2025 23:14:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797286; 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=74Z3rjfmLCK5MKWoQQ9msNIaheYuoK/rIVoIzOZKnX8=; b=VokAtYj8Cn9Ey0ERKLBoTtus3BzxsBzU8+m7UY24LAVdYZQAzmPE8m9A/cqUqSQOwfH/UP 8uPUz6hVf3fTBGVZNjqRBB7EE/ggZZAGSfETd+U5HuAmnVs7N89G9pq2nLX5RpNfiMebLq frdMC8m/eRbbJgoUUf6L5Dcjm3hgGi8= X-MC-Unique: 0Jqo_CvEOgGY7BRezMMVsA-1 X-Mimecast-MFC-AGG-ID: 0Jqo_CvEOgGY7BRezMMVsA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 24/42] docs/qapidoc: add transmogrifier test document Date: Wed, 5 Feb 2025 18:11:50 -0500 Message-ID: <20250205231208.1480762-25-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797524165019000 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/index.rst | 1 + docs/qapi/index.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/qapi/index.rst diff --git a/docs/index.rst b/docs/index.rst index 5665de85cab..4364f9f1618 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,3 +21,4 @@ Welcome to QEMU's documentation! specs/index devel/index glossary + qapi/index diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst new file mode 100644 index 00000000000..e40dce09119 --- /dev/null +++ b/docs/qapi/index.rst @@ -0,0 +1,53 @@ +######################## +QAPI Transmogrifier Test +######################## + +This is a test render of the QEMU QMP reference manual using the new +"transmogrifier" generator in qapidoc.py in conjunction with the +qapi-domain.py sphinx extension. + +Some notable features: + + * Every QAPI definition visible below is available to be + cross-referenced from anywhere else in the Sphinx docs; for example + ```blockdev-add``` will render to `blockdev-add`. + + * There are type-specific cross-referencing roles available for + alternates, commands, events, enums, structs, unions and modules. for + example, ``:qapi:cmd:`block-dirty-bitmap-add``` resolves to + :qapi:cmd:`block-dirty-bitmap-add`, and only works for commands. The + roles available are ``cmd``, ``alt``, ``event``, ``enum``, + ``struct``, ``union``, and ``mod``; with two meta-roles available: + ``obj`` for absolutely any QAPI definition, and ``type`` for + everything except commands, events, and modules. + + * There is a new `qapi-index` page which can be linked to with + ```qapi-index```. There, you can browse a list of all QAPI + definitions by type or alphabetically. + + * QAPI definitions are also added to the existing `genindex` page. + + * All member/argument/return types are now cross-references to that + type's definition. `chardev-add` is a good example. + + * This work-in-progress version does not perform any inlining. + + * This work-in-progress version actually also ignores branches entirely + right now! + + * This version currently does not "prune" unnecessary docs. + + * This version does not add undocumented members or return values. + + * This version does not handle ifcond for anything other than top-level + entity definitions. + + * This version renders sections in precisely the order they appear in + source, even if that winds up looking silly. + + +.. contents:: + :depth: 2 + +.. qapi-doc:: qapi/qapi-schema.json + :transmogrify: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797411; cv=none; d=zohomail.com; s=zohoarc; b=gDlflzfJv2e1krHKA0o6LcfgOO2Hhw7WC4/x+9V9UytUG9Wxjh3EwH3VM+ZLOYqlsddgmynS2z9m1bynpZLejaN1bHQ8daqVgY7ZLdgbuxPYfAVJ5IvJENuDhezGZjMXNW/YBoxnpMD/NcORrxyyGcOeegtV9FrriHUEK+R+ZyQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797411; 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=m9futkH/ebd24DorEZYDcyRn0hD00MnyYySGtGvW7lc=; b=VCMHlhHplKZAdljMZV//GTICmEAUlMO8Sm53xNilJAuI4Oxn27Mbp2H8gu1jYL3JP0EXyuUTjSSQ1JHQpsk2NbnmRfEiuhppOwJo43WDoE5mTLwXH3C9VNG4+E1GIDOLemZdL6rczKDEhd4BDHVhrIzhokoQAQGWkCpRF73Dq+Q= 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 1738797411741914.9065458523468; Wed, 5 Feb 2025 15:16:51 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfobo-0007oz-Hn; Wed, 05 Feb 2025 18:15:08 -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 1tfobh-0007XL-GY for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:57 -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 1tfobd-0005pn-Mv for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:14:55 -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-230-O_x7xatMNxejC_Za19dAKA-1; Wed, 05 Feb 2025 18:14:49 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 E2DEB1956094; Wed, 5 Feb 2025 23:14:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8BDF21800265; Wed, 5 Feb 2025 23:14:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797292; 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=m9futkH/ebd24DorEZYDcyRn0hD00MnyYySGtGvW7lc=; b=eaMqDax9fP30KN+V0Vhc+OgJMeZvyEYwMqXooDcFHlHd0B30pfN0rTCE7ssu4vvJ4K4usH 7kjCm6PiinJDCbdBU0yW+psqWzJPz+sCGjRc3zbaox0+Ay0Fe2OwypeT2VQXllGNVDnQti Q0tr/w2YxLYsHn0vIzwdwWO1ExUYgDI= X-MC-Unique: O_x7xatMNxejC_Za19dAKA-1 X-Mimecast-MFC-AGG-ID: O_x7xatMNxejC_Za19dAKA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 25/42] docs/qapidoc: generate entries for undocumented members Date: Wed, 5 Feb 2025 18:11:51 -0500 Message-ID: <20250205231208.1480762-26-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797414093019100 Content-Type: text/plain; charset="utf-8" Presently, we never have any empty text entries for members. The next patch will explicitly generate such sections, so enable support for it in advance. The parser will generate placeholder sections to indicate undocumented members, but it's the qapidoc generator that's responsible for deciding what to do with that stub section. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5d946a46637..2d83556629d 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -221,11 +221,10 @@ def visit_member(self, section: QAPIDoc.ArgSection) -= > None: # TODO?: features for members (documented at entity-level, # but sometimes defined per-member. Should we add such # information to member descriptions when we can?) - assert section.text self.generate_field( self.member_field_type, section.member, - section.text, + section.text if section.text else "(Not Documented.)", section.info, ) =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797517; cv=none; d=zohomail.com; s=zohoarc; b=cRU0UWLhbMFe++3LVVANptBWhXWCMy0w7I+omYdUOr/fKj4RO6IRKXir3GT+o4tMS67kAl4Z392byLSPB5PkrxNJFlwAXNb0UMoZ5uLyFifW0y/YAaVUodhWZwMbcEJK8iXS5bcB54bKjyTlsS9Lld1I3z7TMUoUFCYeUbNdZ4E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797517; 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=p5a5n4efKymKtAME8NwZAOJy7b6IhV1FNDCgSqtH52E=; b=Z9ZI51ZCthJr6HwPghyDF0ngdgFlbHycgtxg5qTbFNLjvqrrTP+cbaAAkgySsmKpeHVdvfqfi0mkaEESRfrC6I0HQeUFz6A164PaRAv7mBuqzP7iUFOTKA6JOaIWV0kyYzi3CdLOGUh0zIRocsgFkeTYUPq2KkVeuJdvRrwveSM= 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 1738797517906376.45939349237085; Wed, 5 Feb 2025 15:18:37 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfoc4-00082y-FT; Wed, 05 Feb 2025 18:15:24 -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 1tfobk-0007hb-Us for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:01 -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 1tfobj-0005q1-2L for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:00 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-548-s6j-xG_uNI-eTvrM3iEkxw-1; Wed, 05 Feb 2025 18:14:55 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B3CC81800876; Wed, 5 Feb 2025 23:14:53 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 330031800570; Wed, 5 Feb 2025 23:14:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797298; 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=p5a5n4efKymKtAME8NwZAOJy7b6IhV1FNDCgSqtH52E=; b=Myaq7LUgxel6oIyeP7O4PTl+H8aX5vsTD4stDDym5wupHc1NVJebSFi9pcBlGnxdogi8ap 6Wr3mNNbwfmqCjzoUOwS7TzctyCoWjlYTYArN/TiFoDpwyhbDfsr5g7A8AtivMMeAwEnxv vRkgm6VH6Tp8OVFFf+gW8xW2vcS/28Y= X-MC-Unique: s6j-xG_uNI-eTvrM3iEkxw-1 X-Mimecast-MFC-AGG-ID: s6j-xG_uNI-eTvrM3iEkxw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 26/42] qapi/parser: add undocumented stub members to all_sections Date: Wed, 5 Feb 2025 18:11:52 -0500 Message-ID: <20250205231208.1480762-27-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797520447019100 Content-Type: text/plain; charset="utf-8" This helps simplify the new doc generator if it doesn't have to check for undocumented members; especially when dealing recursively with inherited documentation blocks. NB: If there is no existing 'member' section, these undocumented stub members will be inserted directly after the intro paragraph(s). This is potentially problematic for cases where a doc block contains *only* free paragraphs, but some of those paragraphs are conceptually better suited for the "outro" section; i.e.: This patch will insert member documentation after the example, effectively solidifying all preceding paragraphs as "intro" type, which may not be what we want. Solution for this issue is still TBD; auditing is needed to understand how prevalent the problem is to help engineer a fix or decide it's not really a problem that needs solving. While I'm rambling about RFC stuff in the commit message though, this patch really did help cull over a hundred lines from the new generator, so I think I'm predisposed to find a way to keep it. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/parser.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index af5d7bf892c..a8b30ae1a4b 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -800,6 +800,18 @@ def connect_member(self, member: 'QAPISchemaMember') -= > None: section =3D QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) self.args[member.name] =3D section + + # Insert stub documentation section for missing member docs. + # Determine where to insert stub doc - it should go at the + # end of the members section(s), if any. Note that index 0 + # is assumed to be an untagged intro section, even if it is + # empty. + index =3D 1 + if len(self.all_sections) > 1: + while self.all_sections[index].kind =3D=3D QAPIDoc.Kind.ME= MBER: + index +=3D 1 + self.all_sections.insert(index, section) + self.args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797563; cv=none; d=zohomail.com; s=zohoarc; b=DsV8Q78V1OI7pqU/YzAcj+dJYwDVI4m/npXSP9mICOaQgkaka2TJ+PU/ld6lnY91csJZIg84DskOmgccc/5CKBOLpqxkwYoc09d95NhoutkOJ6r/resgLMCurC7nJLfgipr7JGHXjqT1L6BUt8g2Ih5sp9Pk48lULAZFkmAh4Uw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797563; 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=aCyKutJWGOcr8VObj1Oj+4uR8ZmsNxHABIofgBJXEss=; b=cic+6uxBtU2mXZcuCoP9PcW2g+CknCquA0xHe8x1JA3QNx7RoQ03N7WQj99fM9eNhpoQioTM79K2lHi/m75Gs6P4GjwJklNTCnNqqQNOnepvUmQAWkf6mkrTKq0xANpHTCDEgXUTYLhibh5nel+of6zuW/nC1O42EamP4PHdp5I= 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 1738797563625147.78816518587303; Wed, 5 Feb 2025 15:19:23 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocD-0000SO-28; Wed, 05 Feb 2025 18:15:29 -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 1tfobs-00087N-Km for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:12 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfobq-00061W-6K for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:08 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-679-RrnFoDO_Mh6zp2Hc-d4TDQ-1; Wed, 05 Feb 2025 18:15:02 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8C7D61800570; Wed, 5 Feb 2025 23:15:00 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 607FF1800570; Wed, 5 Feb 2025 23:14:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797305; 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=aCyKutJWGOcr8VObj1Oj+4uR8ZmsNxHABIofgBJXEss=; b=QvI+nQQg5AYdawh4iEhU0EiLmH2DmugP/Vc21jUMi+1VB27LFvJTgcQ7FG79rtsHIYoq+9 PqzC/oXCZ1kA85+1hcPVeEbck+FWQasAx4GycJM/foXSkooblSVvElvHci2PaPXbQS5qqV U/tUi1paXCAvbBDSw6YPTXKznbXGnh8= X-MC-Unique: RrnFoDO_Mh6zp2Hc-d4TDQ-1 X-Mimecast-MFC-AGG-ID: RrnFoDO_Mh6zp2Hc-d4TDQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 27/42] qapi: differentiate "intro" and "detail" sections Date: Wed, 5 Feb 2025 18:11:53 -0500 Message-ID: <20250205231208.1480762-28-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797566632019100 Content-Type: text/plain; charset="utf-8" This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of knowing when and where to inline those sections. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 4 ++-- scripts/qapi/parser.py | 30 +++++++++++++++++++----------- tests/qapi-schema/doc-good.out | 8 ++++---- 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 2d83556629d..154ebc1b4cd 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -289,7 +289,7 @@ def visit_sections(self, ent: QAPISchemaEntity) -> None: =20 # Add sections *in the order they are documented*: for section in sections: - if section.kind =3D=3D QAPIDoc.Kind.PLAIN: + if section.kind.name in ("INTRO", "DETAIL"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: self.visit_member(section) @@ -578,7 +578,7 @@ def _nodes_for_sections(self, doc): # Hide TODO: sections continue =20 - if section.kind =3D=3D QAPIDoc.Kind.PLAIN: + if section.kind.name in ("INTRO", "DETAIL"): # Sphinx cannot handle sectionless titles; # Instead, just append the results to the prior section. container =3D nodes.container() diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index a8b30ae1a4b..b2f77ffdd7a 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -499,7 +499,7 @@ def get_doc(self) -> 'QAPIDoc': doc =3D QAPIDoc(info, symbol) self.accept(False) line =3D self.get_doc_line() - no_more_args =3D False + have_tagged =3D False =20 while line is not None: # Blank lines @@ -528,10 +528,10 @@ def get_doc(self) -> 'QAPIDoc': if not doc.features: raise QAPIParseError( self, 'feature descriptions expected') - no_more_args =3D True + have_tagged =3D True elif match :=3D self._match_at_name_colon(line): # description - if no_more_args: + if have_tagged: raise QAPIParseError( self, "description of '@%s:' follows a section" @@ -543,7 +543,7 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line =3D self.get_doc_indented(doc) - no_more_args =3D True + have_tagged =3D True elif match :=3D re.match( r'(Returns|Errors|Since|Notes?|Examples?|TODO)' r'(?!::): *', @@ -584,14 +584,20 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line =3D self.get_doc_indented(doc) - no_more_args =3D True + have_tagged =3D True elif line.startswith('=3D'): raise QAPIParseError( self, "unexpected '=3D' markup in definition documentati= on") else: # plain paragraph(s) - doc.ensure_untagged_section(self.info) + if have_tagged: + no_more_tags =3D True + + # Paragraphs before tagged sections are "intro" paragr= aphs. + # Any appearing after are "detail" paragraphs. + intro =3D not have_tagged + doc.ensure_untagged_section(self.info, intro) doc.append_line(line) line =3D self.get_doc_paragraph(doc) else: @@ -640,21 +646,22 @@ class QAPIDoc: """ =20 class Kind(enum.Enum): - PLAIN =3D 0 + INTRO =3D 0 MEMBER =3D 1 FEATURE =3D 2 RETURNS =3D 3 ERRORS =3D 4 SINCE =3D 5 TODO =3D 6 + DETAIL =3D 7 =20 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind': return QAPIDoc.Kind[kind.upper()] =20 def text_required(self) -> bool: - # Only "plain" sections can be empty - return self.value not in (0,) + # Only Intro/Detail sections can be empty + return self.value not in (0, 7) =20 def __str__(self) -> str: return self.name.title() @@ -700,7 +707,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): self.symbol: Optional[str] =3D symbol # the sections in textual order self.all_sections: List[QAPIDoc.Section] =3D [ - QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) + QAPIDoc.Section(info, QAPIDoc.Kind.INTRO) ] # the body section self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] @@ -725,8 +732,9 @@ def end(self) -> None: def ensure_untagged_section( self, info: QAPISourceInfo, + intro: bool =3D True, ) -> None: - kind =3D QAPIDoc.Kind.PLAIN + kind =3D QAPIDoc.Kind.INTRO if intro else QAPIDoc.Kind.DETAIL =20 if self.all_sections and self.all_sections[-1].kind =3D=3D kind: # extend current section diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 2d33a305ee7..3eb28503f6b 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -110,7 +110,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=3Denum-member-feat a member feature - section=3DPlain + section=3DDetail @two is undocumented doc symbol=3DBase body=3D @@ -168,7 +168,7 @@ description starts on the same line a feature feature=3Dcmd-feat2 another feature - section=3DPlain + section=3DDetail .. note:: @arg3 is undocumented section=3DReturns @Object @@ -176,7 +176,7 @@ another feature some section=3DTodo frobnicate - section=3DPlain + section=3DDetail .. admonition:: Notes =20 - Lorem ipsum dolor sit amet @@ -209,7 +209,7 @@ If you're bored enough to read this, go see a video of = boxed cats a feature feature=3Dcmd-feat2 another feature - section=3DPlain + section=3DDetail .. qmp-example:: =20 -> "this example" --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797521; cv=none; d=zohomail.com; s=zohoarc; b=f4p4e6Trry3yuArTIHMvQ8LpiA5FA81Lx+ZYNSZHq4SElRjUyc36oTaS5THHPuu6WWltvrNn+NQi+/bpb9pJPy/o0Tgq35OcoDXkJ8R7/ib7NMDwfq5hgQ/eYCjVKIflsokLHdS0qYts2cw5FoMXj/fJUNOLFxo/rAqgbuzf+ME= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797521; 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=8PKSfUfVQASo0aYn9iWkW/aHJ0yWG6y6ge07cOtET04=; b=JFAF1CsD0fw+7IXWgdxoHJE00qCJAungoGReNu7HzjRld4hxmYmssDo5FAYF1aYyZC9xvKMfoZEBlg2VWKN026VMrV9C4YD5mBQQKfv8a2U938QaoIu++57XxbDGkeS8vlWG/IbUJBWbaS23g9iSdSeThAMVvLC7YrYFaLod1b8= 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 1738797521772367.8448955337642; Wed, 5 Feb 2025 15:18:41 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocD-0000PT-0h; Wed, 05 Feb 2025 18:15:29 -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 1tfobz-0008Me-TN for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:21 -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 1tfobw-000623-Bb for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:15 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-336-qaIabqK4MnCbPjo5-3U25Q-1; Wed, 05 Feb 2025 18:15:08 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id AB6411800984; Wed, 5 Feb 2025 23:15:06 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 246BB1800570; Wed, 5 Feb 2025 23:15:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797311; 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=8PKSfUfVQASo0aYn9iWkW/aHJ0yWG6y6ge07cOtET04=; b=V8dUUC0cMPU3iRQ6QNmHBIeOQ/HmE1Ai5YhhWsItAYGcaZbi7Q9ACJRqGiWyurov9ZUUYn rZ5IW9qaK2Vg/gof4Qfapj/EmTdb3LUr/WfcQFWodwUtXOuVvPIj+wZUXRy02MVuIcEwws uyeMTx54Coxc7CkUKw5c8jBpAnRSg/k= X-MC-Unique: qaIabqK4MnCbPjo5-3U25Q-1 X-Mimecast-MFC-AGG-ID: qaIabqK4MnCbPjo5-3U25Q From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 28/42] qapi/parser: prohibit untagged sections between tagged sections Date: Wed, 5 Feb 2025 18:11:54 -0500 Message-ID: <20250205231208.1480762-29-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797522191019000 Content-Type: text/plain; charset="utf-8" This is being done primarily to ensure consistency between the source documents and the final, rendered HTML output. Because member/feature/returns sections will always appear in a visually grouped element in the HTML output, prohibiting free paragraphs between those sections ensures ordering consistency between source and the final render. Additionally, prohibiting such "middle" text paragraphs allows us to classify all plain text sections as either "intro" or "detail" sections, because these sections must either appear before structured elements ("intro") or afterwards ("detail"). This keeps the inlining algorithm simpler with fewer "splice" points when inlining multiple documentation blocks. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- qapi/net.json | 4 ++-- qapi/qom.json | 4 ++-- scripts/qapi/parser.py | 16 ++++++++++++++++ tests/qapi-schema/doc-good.json | 4 ++-- tests/qapi-schema/doc-good.out | 4 ++-- tests/qapi-schema/doc-good.txt | 8 ++++---- 6 files changed, 28 insertions(+), 12 deletions(-) diff --git a/qapi/net.json b/qapi/net.json index 2739a2f4233..49bc7de64e9 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -655,13 +655,13 @@ # this to zero disables this function. This member is mutually # exclusive with @reconnect. (default: 0) (Since: 9.2) # -# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. -# # Features: # # @deprecated: Member @reconnect is deprecated. Use @reconnect-ms # instead. # +# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# # Since: 7.2 ## { 'struct': 'NetdevStreamOptions', diff --git a/qapi/qom.json b/qapi/qom.json index 28ce24cd8d0..11277d1f84c 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -195,12 +195,12 @@ # # @typename: the type name of an object # +# Returns: a list of ObjectPropertyInfo describing object properties +# # .. note:: Objects can create properties at runtime, for example to # describe links between different devices and/or objects. These # properties are not included in the output of this command. # -# Returns: a list of ObjectPropertyInfo describing object properties -# # Since: 2.12 ## { 'command': 'qom-list-properties', diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b2f77ffdd7a..c5d2b950a82 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -500,6 +500,20 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line =3D self.get_doc_line() have_tagged =3D False + no_more_tags =3D False + + def _tag_check(what: str) -> None: + if what in ('TODO', 'Since'): + return + + if no_more_tags: + raise QAPIParseError( + self, + f"{what!r} section cannot appear after free " + "paragraphs that follow other tagged sections. " + "Move this section upwards with the preceding " + "tagged sections." + ) =20 while line is not None: # Blank lines @@ -513,6 +527,7 @@ def get_doc(self) -> 'QAPIDoc': if doc.features: raise QAPIParseError( self, "duplicated 'Features:' line") + _tag_check("Features") self.accept(False) line =3D self.get_doc_line() while line =3D=3D '': @@ -576,6 +591,7 @@ def get_doc(self) -> 'QAPIDoc': ) raise QAPIParseError(self, emsg) =20 + _tag_check(match.group(1)) doc.new_tagged_section( self.info, QAPIDoc.Kind.from_string(match.group(1)) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son index f64bf38d854..14b2091b08f 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -157,12 +157,12 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# .. note:: @arg3 is undocumented -# # Returns: @Object # # Errors: some # +# .. note:: @arg3 is undocumented +# # TODO: frobnicate # # .. admonition:: Notes diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 3eb28503f6b..77edadb6e40 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -168,12 +168,12 @@ description starts on the same line a feature feature=3Dcmd-feat2 another feature - section=3DDetail -.. note:: @arg3 is undocumented section=3DReturns @Object section=3DErrors some + section=3DDetail +.. note:: @arg3 is undocumented section=3DTodo frobnicate section=3DDetail diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index cb37db606a6..dc40b3f7046 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -193,10 +193,6 @@ Features "cmd-feat2" another feature =20 -Note: - - "arg3" is undocumented - =20 Returns ~~~~~~~ @@ -209,6 +205,10 @@ Errors =20 some =20 +Note: + + "arg3" is undocumented + Notes: =20 * Lorem ipsum dolor sit amet --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797525; cv=none; d=zohomail.com; s=zohoarc; b=bkM4MlGrpSC9k6crPk1/fQWAU5yXUmzMhVKdfOAWK76WAAgW+mX6VT4TeyaVFo8kTpNeTd6VhKZ0L5XU7IijnXacgK462b1nxJUidjppS3FgS79AwzC024fQhqNtupNSX8bSN+X2S9IWeg8vcn1EDyFXWG7GpOpd6RnigXbnXqI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797525; 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=ocEVIzgCllNidvY9XGuysb7vC/waRLiNKCmS0h9gcRQ=; b=YTzZyod0gR8+38gufvTsUD/+pDBSrKBBtPFwCU/njmeaW4nDKUML9aNF3VLS/lv6Kn1GekbfBXCNajbu/MwlP7Q8AnnFgZBj18EbzU6t4ArPO2axjATgVLhu7v4sYigzq1VeoJ87P+j5cuBFflhMaM8d43WgjhgmCajWJwEGkcY= 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 1738797525509825.308811608232; Wed, 5 Feb 2025 15:18:45 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocH-0000rB-5R; Wed, 05 Feb 2025 18:15:33 -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 1tfoc7-00009Q-9Q for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:24 -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 1tfoc5-00062k-HY for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:23 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-600-htWgkY6PMOiJpafevoan7Q-1; Wed, 05 Feb 2025 18:15:15 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 25DEB180087F; Wed, 5 Feb 2025 23:15:13 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3D7B71800570; Wed, 5 Feb 2025 23:15:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797319; 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=ocEVIzgCllNidvY9XGuysb7vC/waRLiNKCmS0h9gcRQ=; b=YYSM/NRRQFpYDSUGe+9b+2PPLnQFZwq5hQzNOMRThBhH/cE6rwPrr5Sc8r+Z2DkWgXQLlf Jf/GUNwvDkjNDEsbe62/9stZvVuX/6QHzHbmT25dfmXzFSSRYfcPHSQJUAYatEu7up8VHh NrtUmZF9n+wFJzBgVC2vOmr6XmAFyHQ= X-MC-Unique: htWgkY6PMOiJpafevoan7Q-1 X-Mimecast-MFC-AGG-ID: htWgkY6PMOiJpafevoan7Q From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 29/42] qapi: Add "Details:" disambiguation marker Date: Wed, 5 Feb 2025 18:11:55 -0500 Message-ID: <20250205231208.1480762-30-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797551878019000 Content-Type: text/plain; charset="utf-8" This clarifies sections that are mistaken by the parser as "intro" sections to be "details" sections instead. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- qapi/machine.json | 2 ++ qapi/migration.json | 4 ++++ qapi/qom.json | 4 ++++ qapi/yank.json | 2 ++ scripts/qapi/parser.py | 8 ++++++++ 5 files changed, 20 insertions(+) diff --git a/qapi/machine.json b/qapi/machine.json index a6b8795b09e..3c1b397f6cc 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1301,6 +1301,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # +# Details: +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } diff --git a/qapi/migration.json b/qapi/migration.json index 43babd1df41..9070a91e655 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1920,6 +1920,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # +# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" } @@ -1993,6 +1995,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" } diff --git a/qapi/qom.json b/qapi/qom.json index 11277d1f84c..5d285ef9239 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -729,6 +729,8 @@ # # Properties for memory-backend-shm objects. # +# Details: +# # This memory backend supports only shared memory, which is the # default. # @@ -744,6 +746,8 @@ # # Properties for memory-backend-epc objects. # +# Details: +# # The @merge boolean option is false by default with epc # # The @dump boolean option is false by default with epc diff --git a/qapi/yank.json b/qapi/yank.json index 30f46c97c98..4d36d21e76a 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -104,6 +104,8 @@ # # Returns: list of @YankInstance # +# Details: +# # .. qmp-example:: # # -> { "execute": "query-yank" } diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c5d2b950a82..5890a13b5ba 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -544,6 +544,14 @@ def _tag_check(what: str) -> None: raise QAPIParseError( self, 'feature descriptions expected') have_tagged =3D True + elif line =3D=3D 'Details:': + _tag_check("Details") + self.accept(False) + line =3D self.get_doc_line() + while line =3D=3D '': + self.accept(False) + line =3D self.get_doc_line() + have_tagged =3D True elif match :=3D self._match_at_name_colon(line): # description if have_tagged: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797449; cv=none; d=zohomail.com; s=zohoarc; b=YwgwLWBpTQTSzwZq8VyhFv4ymqCg+5USb1GDSpDTEmnghQXr2osvfHhfCsl0j0r92WyMgXU5QePZZDX+g4qWgblYt+e8d2CnaROOOSUxbYvD0C5IkeZRTSW6EbqoQ93W1ImPEIgyfIoW3B4FezhiZaLAk1X7cpdAsHx4mYZ/4GA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797449; 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=5pQpG+9Zm4aFqSNny8uokAA9FhDNi6AirSzCVGIFntA=; b=b6n5qrLNZgezGlT5l+jyA4z7QUq3Zs5/YpFSl73MR5mFm+Vuq0kr5fAcvhEJLTgIii6j16Y2jNzMvWkvtlqUov6yjginAtV0AD5L8fuYcJNSSsGkxfi6fRrqDVlYnde0AvQQ08Pn9Srcbb4Chk5pOu+yb3nE3UhwxI+oQ/wOGyA= 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 1738797449365411.1498204798521; Wed, 5 Feb 2025 15:17:29 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocH-0000wQ-8c; Wed, 05 Feb 2025 18:15:33 -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 1tfocB-0000NB-Sz for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:28 -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 1tfoc9-00063H-Nm for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:27 -0500 Received: from mx-prod-mc-02.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-616-yqUHXDsMM-eTOq7JYAnupQ-1; Wed, 05 Feb 2025 18:15:21 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 47E141956086; Wed, 5 Feb 2025 23:15:19 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 857CF1800570; Wed, 5 Feb 2025 23:15:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797324; 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=5pQpG+9Zm4aFqSNny8uokAA9FhDNi6AirSzCVGIFntA=; b=De1VAP9IAzAueLk3Pdbj91vtY08MSwDPor6O65PG7LlCx5SWBf9v0/DQAxjZipPm0rdwUe +JOx+OJYFjKOiw9jhAF92yxC/gAcUy6QgQvkbaQy+1Ko9Zxa+S5bicKJWFS1qezIgAgVKU E6Pa8t7wr7GPXPsNuJOl1MaS6Bs6ZaM= X-MC-Unique: yqUHXDsMM-eTOq7JYAnupQ-1 X-Mimecast-MFC-AGG-ID: yqUHXDsMM-eTOq7JYAnupQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 30/42] docs/qapidoc: add minimalistic inliner Date: Wed, 5 Feb 2025 18:11:56 -0500 Message-ID: <20250205231208.1480762-31-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797452329019100 Content-Type: text/plain; charset="utf-8" Add a minimalistic inliner that only gets the basics - leaving branch inlining for a future patch. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 174 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 172 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 154ebc1b4cd..538c26e812d 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -25,13 +25,15 @@ https://www.sphinx-doc.org/en/master/development/index.html """ =20 +from collections import defaultdict from contextlib import contextmanager +import enum import os from pathlib import Path import re import sys import textwrap -from typing import List, Optional +from typing import Dict, List, Optional =20 from docutils import nodes from docutils.parsers.rst import Directive, directives @@ -45,8 +47,10 @@ QAPISchemaCommand, QAPISchemaEntity, QAPISchemaEnumMember, + QAPISchemaEvent, QAPISchemaFeature, QAPISchemaMember, + QAPISchemaObjectType, QAPISchemaObjectTypeMember, ) from qapi.source import QAPISourceInfo @@ -77,6 +81,172 @@ def dedent(text: str) -> str: return lines[0] + textwrap.dedent("".join(lines[1:])) =20 =20 +class DocRegion(enum.Enum): + # The inliner introduces the concept of doc Regions, which are + # groupings of zero or more Sections. These regions are used to know + # how to combine two lists of Sections. + INTRO =3D 0 + MEMBER =3D 1 + OTHER =3D 2 + FEATURE =3D 3 + DETAIL =3D 4 + + @staticmethod + def categorize(section: QAPIDoc.Section) -> "Optional[DocRegion]": + return MAPPING[section.kind] + + +MAPPING =3D { + QAPIDoc.Kind.INTRO: DocRegion.INTRO, + QAPIDoc.Kind.MEMBER: DocRegion.MEMBER, + QAPIDoc.Kind.FEATURE: DocRegion.FEATURE, + QAPIDoc.Kind.RETURNS: DocRegion.OTHER, + QAPIDoc.Kind.ERRORS: DocRegion.OTHER, + QAPIDoc.Kind.SINCE: None, + QAPIDoc.Kind.TODO: None, + QAPIDoc.Kind.DETAIL: DocRegion.DETAIL, +} + + +class InlinerSections: + + def __init__(self, sections): + self._sections: List[QAPIDoc.Section] =3D list(sections) + self.partitions: Dict[DocRegion, List[QAPIDoc.Section]] =3D defaul= tdict( + list + ) + self._modified =3D False + + self._partition() + + def _partition(self): + for section in self._sections: + # suppress empty text sections for the purpose of, later, + # being able to determine if a collection of doc sections + # "has an intro" or "has a details section" or not, which is + # helpful later on for some assertions about the inliner. + if section.kind in (QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAIL): + if not section.text: + continue + + region =3D DocRegion.categorize(section) + if region is None: + continue + + self.partitions[region].append(section) + + def absorb(self, other: "InlinerSections"): + for category, oval in other.partitions.items(): + val =3D self.partitions[category] + if category =3D=3D DocRegion.INTRO: + # The intro region is not inlined, it is dropped. + continue + + # Everything else is prepended. + self.partitions[category] =3D oval + val + if oval: + self._modified =3D True + + def __iter__(self): + return iter(self._flatten()) + + def _flatten(self): + # Serialize back into a normal list. + + # If nothing has changed, we don't need to do anything. + if not self._modified: + return tuple(self._sections) + + # Otherwise, we need to rebuild the sequence. + # + # FIXME: This function assumes a stricter ordering of regions + # within the source docs (see DocRegion); This order is not + # currently enforced in parser.py, so this method may shift some + # contents around compared to the source. + tmp =3D [] + for category in DocRegion: + tmp.extend(self.partitions[category]) + self._sections =3D tmp + self._modified =3D False + return tuple(self._sections) + + +def inline(ent: QAPISchemaEntity) -> List[QAPIDoc.Section]: + """ + Return all of an entity's doc sections with inlined sections stitched = in. + + First, a given entity's sections are retrieved in full, in source orde= r. + + Next, if this entity has either an argument type (Commands and + Events) or an inherited base (Structs, Unions), this function is + called recursively on that type to retrieve its sections. These + sections are then stitched into the result. + + Lastly, if this entity has any branches, this function is called + recursively on each branch type and those sections are stitched into + the result. + + STITCH ORDER: + + - Introduction + - [Inlined introduction sections are dropped.] + - Recursively inlined Members + - Members + - Recursively inlined Branch members + - Other special sections (Errors, Returns) + - [There are no cases where we have these sections to inline.] + - Recursively inlined Features + - Features + - Recursively inlined Details + - Details + + Intro paragraphs are never stitched into the documentation section + list. Members, Features, and Details paragraphs are stitched in + *before* the given entity's equivalent regions. Individual sections + otherwise appear in source order as they do in the parent or child. + + Branch members are stitched in *after* the member section. + + In the event that a paragraph cannot be determined to be an intro or + details type, a warning is emitted. It will be treated as an intro + section and dropped from the output. QEMU usually treats Sphinx + warnings as fatal, so this warning is usually fatal. + """ + + def _sections(ent) -> List[QAPIDoc.Section]: + return ent.doc.all_sections if ent.doc else [] + + def _get_inline_target( + ent: QAPISchemaEntity, + ) -> Optional[QAPISchemaEntity]: + """Get the entity to inline from for a given entity.""" + if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)): + return ent.arg_type + if isinstance(ent, QAPISchemaObjectType): + return ent.base + return None + + # Let's do this thing! + + if ent is None: + return [] + + # Grab all directly documented sections for the entity in question. + sections =3D InlinerSections(_sections(ent)) + + # Get inlined sections: this includes everything from the + # inlined entity (and anything it inlines, too). + inlined =3D InlinerSections(inline(_get_inline_target(ent))) + + # Now, stitch the results together! + sections.absorb(inlined) + + # FIXME: Branches should be handled about here O:-) + + # Return the combined list of sections. + return list(sections) + + class Transmogrifier: # Field names used for different entity types: field_types =3D { @@ -285,7 +455,7 @@ def preamble(self, ent: QAPISchemaEntity) -> None: self.ensure_blank_line() =20 def visit_sections(self, ent: QAPISchemaEntity) -> None: - sections =3D ent.doc.all_sections if ent.doc else [] + sections =3D inline(ent) =20 # Add sections *in the order they are documented*: for section in sections: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797447; cv=none; d=zohomail.com; s=zohoarc; b=C5we1T0pBqHzCySKRLnxjVWaW2mqZg8Ebc0NDtHNUsKIocEBdFkwTMCaLuTSh+ZWHhpDLX8TaY1wI40uQdZe4+UuzRC3EaKC7/mWg2gcRYXkVN5NvmvmyEs8zmOakCO3WanW9AbqbyNzbBD+hT8EwOsg+e+vMFDmUsGvwwbnN6E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797447; 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=R8q0WYBtgPbrxavnpeYV09ffJck3G5AT6jE50aGCFuo=; b=XM6FVvORwxohS8lIRXLVS1VXkfxraVvG+Nz219ycROjovMjDUHVcc5mOM4m6b1X26HxVm9CApCno+qNy5DfIKHluEuMPNk+sJhvEsKtvamK6ZB49PpotmQjFA6BG0Giwh7th+7IjOLyd0wjFWpXLkBYVfSo9ZyqVSe0SdDRoTm0= 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 1738797447451279.33441845894833; Wed, 5 Feb 2025 15:17:27 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocL-0001RP-DX; Wed, 05 Feb 2025 18:15:37 -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 1tfocH-0000zo-8a for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:33 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfocF-00064B-Gi for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:33 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-669-pmnLvOPhNR-WW32AtuxZIg-1; Wed, 05 Feb 2025 18:15:27 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 87231180087A; Wed, 5 Feb 2025 23:15:25 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id DB9701800570; Wed, 5 Feb 2025 23:15:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797330; 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=R8q0WYBtgPbrxavnpeYV09ffJck3G5AT6jE50aGCFuo=; b=YELVrBsQYDFFwo/vcaFl1H4+kwimiqbHI5iVhFEU+GUzS2JaNNqt9jhzcEzYRQcdH1Fssr Na2e3PvMusUHx7GwHtdZRrbqmU81dLr7DZNqPp8bwlvtSV3QKJ+yVUkhanCF78ACvLmCmU W3cx0umQWoqb1AfKGL77oxMe5zyDlRI= X-MC-Unique: pmnLvOPhNR-WW32AtuxZIg-1 X-Mimecast-MFC-AGG-ID: pmnLvOPhNR-WW32AtuxZIg From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 31/42] docs/qapidoc: autogenerate undocumented return docs Date: Wed, 5 Feb 2025 18:11:57 -0500 Message-ID: <20250205231208.1480762-32-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797447882019000 Content-Type: text/plain; charset="utf-8" This patch adds support for handling undocumented returns values sections -- which aren't actually implemented until the next patch. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 538c26e812d..b9fe2f476cb 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -410,15 +410,21 @@ def visit_feature(self, section: QAPIDoc.ArgSection) = -> None: def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) rtype =3D self.entity.ret_type - # q_empty can produce None, but we won't be documenting anything - # without an explicit return statement in the doc block, and we - # should not have any such explicit statements when there is no - # return value. - assert rtype + + if not rtype: + # Markus prefers q_empty returning commands just say + # nothing. I'd like a "Returns nothing" in the generated + # docs because I like explicit to implicit - Users may not + # know that commands have an implicit return type and may + # wrongly assume that a missing "Returns" statement means + # it's undocumented. Well, that's my $0.02. + return =20 typ =3D self.format_type(rtype) - assert section.text # We don't expect empty returns sections. - self.add_field("returns", typ, section.text, section.info) + if section.text: + self.add_field("returns", typ, section.text, section.info) + else: + self.add_lines(f":returns-nodesc: {typ}", section.info) =20 def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and may --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797476; cv=none; d=zohomail.com; s=zohoarc; b=U5OpInqZthYuSmVLD98n4Tnd/MixLrZ921YaBz9dBAayuDkkFlsnAj2rAXCPW7vHOxSpDFIBFqh7zNMaSMjB5BTpcfwNnblq75pD7varNICcU3lfxxZJeRc4DaVHZr34yOwAaV59m3FGnU45tpHgnCgI2s0y5nADy/JqKrlQHQM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797476; 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=HGQzUOGkYPNjVTBU4zzr+Xt4CX1F1lTyaUAlIivtS+c=; b=BOhK1wi18Xn+rmLF4PrysHXqa/0tKB+cSMgMj6EOwRCQvmPrTXpBfa8gR+ZCfNFV8kZROyt6r64yzQjAeqbeFL2tg5jpcJfeSwXkwJgAe1GA2UVW7rX6fg+2Xan06gwM8DBYuH0XHsJj8efC6MX0zdjjbAPDw++7bl2vRMpgxcE= 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 1738797476008961.5147639134716; Wed, 5 Feb 2025 15:17:56 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocg-0002SH-1k; Wed, 05 Feb 2025 18:15:58 -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 1tfocU-0002By-8c for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:46 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfocQ-000663-IL for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:45 -0500 Received: from mx-prod-mc-03.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-377-kww7hkHTPIGqXBQ1Gt_gLw-1; Wed, 05 Feb 2025 18:15:34 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9CBD419560BC; Wed, 5 Feb 2025 23:15:32 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 24E481800265; Wed, 5 Feb 2025 23:15:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797338; 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=HGQzUOGkYPNjVTBU4zzr+Xt4CX1F1lTyaUAlIivtS+c=; b=gNoZUS/SD06LG40y6Z3AEksRW3IXDpoiwCPUj7O6Y20pM2x1np4HuwvuDpJ9BTO4K7Ct5I 0AAJIEP3aKK4iOJ5cq3pKEeuU2ni8EZ3QQ3r961+jvR61s1SyU0nWHDuF0bhnuXFuCqEWA Z9MgrEoDT5qojiwy1M/P9IQY+dNGk+Y= X-MC-Unique: kww7hkHTPIGqXBQ1Gt_gLw-1 X-Mimecast-MFC-AGG-ID: kww7hkHTPIGqXBQ1Gt_gLw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 32/42] docs/qapidoc: Add generated returns documentation to inliner Date: Wed, 5 Feb 2025 18:11:58 -0500 Message-ID: <20250205231208.1480762-33-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797478494019100 Content-Type: text/plain; charset="utf-8" Generate "empty" returns sections for undocumented returns values in the inliner: the transmogrifier will pick these up and document them specially. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b9fe2f476cb..5c65f3a8025 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -243,6 +243,14 @@ def _get_inline_target( =20 # FIXME: Branches should be handled about here O:-) =20 + # Generated "returns" statement. + if isinstance(ent, QAPISchemaCommand) and not any( + s.kind =3D=3D QAPIDoc.Kind.RETURNS + for s in sections.partitions[DocRegion.OTHER] + ): + sect =3D QAPIDoc.Section(ent.info, QAPIDoc.Kind.RETURNS) + sections.partitions[DocRegion.OTHER].append(sect) + # Return the combined list of sections. return list(sections) =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797526; cv=none; d=zohomail.com; s=zohoarc; b=ml7Zo97IycDq4O1ZpswKPvgJcABTD7Z/JlfpXnlz3TdAw32gRiEMWCOIfQh9SluMfBfUAZ+ubzTUwjuz06+8nIuZ4W7j+Y3NfWu4n9b31uXAfaXf4QpzhRpX9YGj1vQKeQGTnmG+PQjq8VecgrX6rYkARM0pL8S+itUO46SOmwA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797526; 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=2q5bhksPoiCxanHmvPQ7o2n/l9UjpHDjKW0NSj4q+ZU=; b=cLkJqbihCypYSr9PZ3fVwrTwlfnRuIRxe8HLusvjtOz5noADGftLQf65i6CilQYOTiwXHE+OvN08zvESWoy+VQwRonGUnJX0zSK4QDW85GiuCDzuteVzv/KHo93eP1cTApHSVZEtOre9Th1QjPoIHdu9HiT6VNz+NywCaMTy4r8= 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 1738797526495173.5000710540943; Wed, 5 Feb 2025 15:18:46 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocu-0002pn-Gj; Wed, 05 Feb 2025 18:16:23 -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 1tfocU-0002CD-DR for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:46 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfocS-0006Aj-MY for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:45 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-283-vy-MiG4vPAu0U12bdn-PIQ-1; Wed, 05 Feb 2025 18:15:40 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id AAA081800877; Wed, 5 Feb 2025 23:15:38 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 0CB231800570; Wed, 5 Feb 2025 23:15:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797343; 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=2q5bhksPoiCxanHmvPQ7o2n/l9UjpHDjKW0NSj4q+ZU=; b=QO/aSVhS3MjMq7/yor04h5DBnENEwlxJn1Wi/Ld9pHR5+1PwDp5v/FaPgd9Mj+mZIBsphe 907qpA2us6rraZ7q4Kgikyt4Yiw2R9/iUFiP7+IPiR0+AAB2kGCdfWbvz86/FOOFlQb8o1 BMQrOiOZyil8bBOMEXqNEYq8LSsbDyU= X-MC-Unique: vy-MiG4vPAu0U12bdn-PIQ-1 X-Mimecast-MFC-AGG-ID: vy-MiG4vPAu0U12bdn-PIQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 33/42] docs/qmp: add target to Out-of-band execution section Date: Wed, 5 Feb 2025 18:11:59 -0500 Message-ID: <20250205231208.1480762-34-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797529321019100 Content-Type: text/plain; charset="utf-8" This allows us to cross-reference this section from other docs; the main motivator here is to refer to this section when documenting the Out-of-band capability for QMP commands that support it in the rendered HTML documentation. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/interop/qmp-spec.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst index 563344160e6..ea713a96ac0 100644 --- a/docs/interop/qmp-spec.rst +++ b/docs/interop/qmp-spec.rst @@ -119,6 +119,8 @@ Where: =20 The actual commands are documented in the :doc:`qemu-qmp-ref`. =20 +.. _out-of-band execution: + Out-of-band execution --------------------- =20 --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797393; cv=none; d=zohomail.com; s=zohoarc; b=aGg19kVtluyizmp+r8ZVHLQlNz+1N10DiDRfiSB1YMZVDFSgWVykIPalqryK7TKF8gTyqft8JReIVY/2IJOI5QN88EOSc2OSKZaayKZIWDYKsZbkPzEFwyULa2iAtjReBGQasQGx/UHIxj+rgZxHedMKleHX376PC6jG1Tww8js= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797393; 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=e1nXQRB0gq61g6CFwyR/nEelwMCHxNNP2QX+vNSesCs=; b=Q2iVduoT0R9Cpkd1z5MjmWieCkKe9Q2g4ppSlHLds1XEdwQqwN5J3X4m52E2p/R/3tcqdJzsZ2/ezbbg0UP8hRnQZQjSfqCXjWgGLyimP0wCaCtdcjw6rXSWBC7d54OhNQLjtmzS4147g8szvVAalShyAn/jhOGQbHr5ol/Zdog= 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 1738797393184390.4851631471645; Wed, 5 Feb 2025 15:16:33 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocw-0002qb-RF; Wed, 05 Feb 2025 18:16:23 -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 1tfocb-0002NS-Mb for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:54 -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 1tfocZ-0006EI-2Q for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:52 -0500 Received: from mx-prod-mc-03.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-644-F9ExWoRWNFC9LdrfFMZIfw-1; Wed, 05 Feb 2025 18:15:46 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 605121955F28; Wed, 5 Feb 2025 23:15:44 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id F13461800570; Wed, 5 Feb 2025 23:15:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797349; 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=e1nXQRB0gq61g6CFwyR/nEelwMCHxNNP2QX+vNSesCs=; b=OYUf5whmI/WDxI94FDmmIOB75NCrEG3SiTQcIBMzFknOZUYCAQSnDZZHFNNW/QDMmfJ2f8 88kUbKpeGS2AEm9wMbg+WfShP2yqrCsYT1UzDec+K1HPK/0l7YHcp1PrcKCE4GqHNYSI6X ZmgYXXkTbh34/zhmu4u+qrwjLz+cqmM= X-MC-Unique: F9ExWoRWNFC9LdrfFMZIfw-1 X-Mimecast-MFC-AGG-ID: F9ExWoRWNFC9LdrfFMZIfw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 34/42] docs/qapidoc: document the "out-of-band" pseudofeature Date: Wed, 5 Feb 2025 18:12:00 -0500 Message-ID: <20250205231208.1480762-35-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797393694019000 Content-Type: text/plain; charset="utf-8" Add support to the transmogrifier for documenting the "out-of-band" "pseudofeature" of QMP commands. This patch relies on the inliner adding a dummy feature based on the presence of the oob flag for a QMP command, which happens in the next commit. A "pseudofeature" as I'm terming it here is not associated with a particular member, unlike a standard real-deal feature. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5c65f3a8025..e70a85a6403 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -411,9 +411,15 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -= > None: # Proposal: decorate the right-hand column with some graphical # element to indicate conditional availability? assert section.text # Guaranteed by parser.py - assert section.member =20 - self.generate_field("feat", section.member, section.text, section.= info) + if section.member: + # Normal feature + self.generate_field( + "feat", section.member, section.text, section.info + ) + else: + # Pseudo-feature (OOB) + self.add_field("feat", section.name, section.text, section.inf= o) =20 def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797522; cv=none; d=zohomail.com; s=zohoarc; b=In+oXm8gLQoi0er633yVOZtJJZZK+OIeuPR+hpLYmX30u/GzYjT2SKmovIg96CwtQvk/Sa13ueenWJEy5qfSouSGr6rFj1YFx97Au1rWftS31Nc12jyidHhoDtlXQ9x5r6a/ZaA36o5qMRBkAeruqkDm0KP3H+W6s+4K7q5tNss= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797522; 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=IHIxoPvKeLIyYkefng7YSQobtR2GjSRxfS7Jhn3AbE8=; b=bhaLqyxJuTRlJhv7EOrvzlA+KGrEJNYod4xCXqfz2/bmGin8DyVV+68BBqH4UQ9kKQTZiRUbGVcCrU2bCdBtU1c0gXEvq3wcMuwI9deLftKjob9gAomPdtYG3gSIrGL4WOj6ZVVb1sirkrEeViGEfarBDO6hraQeMr8eYvafwEQ= 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 1738797522068836.1604432178183; Wed, 5 Feb 2025 15:18:42 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfocn-0002mk-9e; Wed, 05 Feb 2025 18:16:05 -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 1tfocf-0002WM-CH for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:58 -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 1tfocd-0006GF-Ow for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:15:57 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-90-LYEq5sQoOkCEXY3X1l_WUw-1; Wed, 05 Feb 2025 18:15:52 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 460CA1800264; Wed, 5 Feb 2025 23:15:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C0F9E1800570; Wed, 5 Feb 2025 23:15:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797355; 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=IHIxoPvKeLIyYkefng7YSQobtR2GjSRxfS7Jhn3AbE8=; b=cIL0RUB3a2sSX0YlkqgagwI1FaM1lNtomv8nmNz0dN4bRHVd0DyIE2A9T6JCdw09uf8SQu nnY6e7qmZ4RgFF6yWZLqdJz/+YB+/JPs/V3bnTxk3aRYHhXBfCyjR1+lGnKg1ke74zUKH5 j7SqKyTJ+d1NTtpLBrzW7LUSMCCSzC0= X-MC-Unique: LYEq5sQoOkCEXY3X1l_WUw-1 X-Mimecast-MFC-AGG-ID: LYEq5sQoOkCEXY3X1l_WUw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 35/42] docs/qapidoc: generate out-of-band pseudofeature sections Date: Wed, 5 Feb 2025 18:12:01 -0500 Message-ID: <20250205231208.1480762-36-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797524387019100 Content-Type: text/plain; charset="utf-8" For QMP commands with the oob flag set, insert a dummy feature ("pseudofeature") representing this behavior so that it can be documented. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index e70a85a6403..81133b9b441 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -243,6 +243,12 @@ def _get_inline_target( =20 # FIXME: Branches should be handled about here O:-) =20 + # Pseudo-feature: document the OOB property. + if isinstance(ent, QAPISchemaCommand) and ent.allow_oob: + feat =3D QAPIDoc.ArgSection(ent.info, QAPIDoc.Kind.FEATURE, "allow= -oob") + feat.append_line("This command supports `out-of-band execution`.") + sections.partitions[DocRegion.FEATURE].append(feat) + # Generated "returns" statement. if isinstance(ent, QAPISchemaCommand) and not any( s.kind =3D=3D QAPIDoc.Kind.RETURNS --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797477; cv=none; d=zohomail.com; s=zohoarc; b=CAfCpEFSbvsYc3HevGFXZ9ZNAKxjkkWskHoCwG+sM6+De9mNEGjkivXtumrL7lQPiKJfLMIUAFJs5VfUh5VdzWIlRJ8m0hnkSJXdFvcAgtE6gVHvezBjBzdhdt/kSi5nTuHgmrNwMVkPE8rvFTpqpV3jCPUq6B6s0KL4gUyJ5qY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797477; 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=aM/k1aBVrX5LbuN3fvXOrQB5zCHh8SMeQZaRxBqvIxA=; b=W74r/92B67ePM0TGj4XFa1V/MCVXxwUh7+0glXNnz0z9+sflniPGjDMRNTZaKfuz3ep3Rg/rET4tmdszqIGvxq7/SWNg12BbaOE2NDoXR8MApUKtpzsVxTvaApaaoZG+Qe5lkQWxBbHJM2HT/du0TIyq/sDq86S75SPzrJL0ByU= 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 1738797477639420.27689260912337; Wed, 5 Feb 2025 15:17:57 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodC-0003HM-Ia; Wed, 05 Feb 2025 18:16:30 -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 1tfoco-0002rN-9Z for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:08 -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 1tfocm-0006Se-Qo for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:06 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-672-zUmgoklzMxmoG-K-aZ2KjQ-1; Wed, 05 Feb 2025 18:16:00 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 437011800268; Wed, 5 Feb 2025 23:15:58 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B95B81800265; Wed, 5 Feb 2025 23:15:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797364; 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=aM/k1aBVrX5LbuN3fvXOrQB5zCHh8SMeQZaRxBqvIxA=; b=ZD9+1Jwid3Zr6AfU6VW+TFkzMvHmH5C9Kipe25gP1gzdIxIMUT4q/5hE2jUjseO8kyTuWY Rnvyk/Kx5m/AF54QQiIAF+ekO8wFjbAstoh38RM1p//dTgc7cI78g9WKqfk5Ry00W7xX6W nTE9fpZdC3nNKemjOUnQWJ+haIZIYEw= X-MC-Unique: zUmgoklzMxmoG-K-aZ2KjQ-1 X-Mimecast-MFC-AGG-ID: zUmgoklzMxmoG-K-aZ2KjQ From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 36/42] qapi/parser: add "meta" kind to QAPIDoc.Kind Date: Wed, 5 Feb 2025 18:12:02 -0500 Message-ID: <20250205231208.1480762-37-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797480252019100 Content-Type: text/plain; charset="utf-8" This adds a "META" category for sections, for the express purpose of adding empty branch-start and branch-end sections into a linear section list for the purpose of rendering collapsible branches in sphinx HTML output. This is ... a little hacky. Sorry. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/parser.py | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 5890a13b5ba..c92bbc908e7 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -678,6 +678,7 @@ class Kind(enum.Enum): SINCE =3D 5 TODO =3D 6 DETAIL =3D 7 + META =3D 8 =20 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind': --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797411; cv=none; d=zohomail.com; s=zohoarc; b=JoetnGOAtM/ROMnoVmWJqPYxsbCAiZ7mOLTFy7DN+cZC7KuXN8iB1dMe2TVTp3OshNyLq8sDj/GWzqmdFklsRkTzN4TM0oW0iwpQ986PAoEzNHcXbyQ9UiZPxtuhOeI/Zp9qo+RJjhWapFeheVrwDTs4oKcoAbYO9o3ofsbshRc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797411; 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=kZ4ptJK3jOz6/9nCnwYuhTipEGLIpTu/jDPEuN8oFBM=; b=IRHU5ixFz0CByeW3kn6/9/0GDhPVxVyG98N8zYrVW0iG8+cGPCuNhpXZVvEWfedd2+NlS/Ng1Z050I6q1FxKzMWdJmm2HxNX+hdJ7fUR0hIjrOSr9ZhJQuItBtYJcVB/RuaxaJSwEduPwq2JoYxGHk3u0XLOmrssdR8ncM8xOa4= 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 1738797411812751.602634825446; Wed, 5 Feb 2025 15:16:51 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodC-0003KY-MJ; Wed, 05 Feb 2025 18:16:30 -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 1tfod7-00030r-9t for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:26 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfocp-0006Y2-Sj for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:10 -0500 Received: from mx-prod-mc-03.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-695-8QRaCY-GOLK8tkrfdah5Lw-1; Wed, 05 Feb 2025 18:16:05 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1531819560B6; Wed, 5 Feb 2025 23:16:04 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 91FB21800570; Wed, 5 Feb 2025 23:15:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797367; 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=kZ4ptJK3jOz6/9nCnwYuhTipEGLIpTu/jDPEuN8oFBM=; b=NLjCBsrkmTESOt9IDVObqAJY9tQ2xA+DzDN6tNhcF6CnYyPGmsOYvmMHl9JCanoJcvJVCW oPZ1om1Vv1frCdzgk1PmJzIcOpmfic6VsBx7xNb1l2HI7ObhHi22Z7T7T0Hl+cX/R/IeUA A9lbB6l/ocMydPpb4d9ivm6Ws7YwF4o= X-MC-Unique: 8QRaCY-GOLK8tkrfdah5Lw-1 X-Mimecast-MFC-AGG-ID: 8QRaCY-GOLK8tkrfdah5Lw From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 37/42] qapi/schema: add __iter__ method to QAPISchemaVariants Date: Wed, 5 Feb 2025 18:12:03 -0500 Message-ID: <20250205231208.1480762-38-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797414160019100 Content-Type: text/plain; charset="utf-8" This is just semantic sugar that makes it easier to do something like: for var in variants: ... Instead of the more cumbersome and repetitive: for var in variants.variants: ... Especially in conjunction with entities that aren't guaranteed to have variants. Compare: for var in variants.variants if variants else []: ... against: for var in variants or []: ... Update callsites to reflect the new usage pattern. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/introspect.py | 4 ++-- scripts/qapi/schema.py | 8 ++++++-- scripts/qapi/types.py | 4 ++-- scripts/qapi/visit.py | 4 ++-- 5 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 81133b9b441..755eb0fa0ec 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -695,7 +695,7 @@ def _nodes_for_members(self, doc, what, base=3DNone, br= anches=3DNone): None) =20 if branches: - for v in branches.variants: + for v in branches: if v.type.name =3D=3D 'q_empty': continue assert not v.type.is_implicit() diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py index ac14b20f308..6ec34e055d3 100644 --- a/scripts/qapi/introspect.py +++ b/scripts/qapi/introspect.py @@ -342,7 +342,7 @@ def visit_object_type_flat(self, name: str, info: Optio= nal[QAPISourceInfo], } if branches: obj['tag'] =3D branches.tag_member.name - obj['variants'] =3D [self._gen_variant(v) for v in branches.va= riants] + obj['variants'] =3D [self._gen_variant(v) for v in branches] self._gen_tree(name, 'object', obj, ifcond, features) =20 def visit_alternate_type(self, name: str, info: Optional[QAPISourceInf= o], @@ -353,7 +353,7 @@ def visit_alternate_type(self, name: str, info: Optiona= l[QAPISourceInfo], name, 'alternate', {'members': [Annotated({'type': self._use_type(m.type)}, m.ifcond) - for m in alternatives.variants]}, + for m in alternatives]}, ifcond, features ) =20 diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index e97c978d38d..4c55f7640b6 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -26,6 +26,7 @@ Any, Callable, Dict, + Iterator, List, Optional, Union, @@ -669,7 +670,7 @@ def check(self, schema: QAPISchema) -> None: # so we have to check for potential name collisions ourselves. seen: Dict[str, QAPISchemaMember] =3D {} types_seen: Dict[str, str] =3D {} - for v in self.alternatives.variants: + for v in self.alternatives: v.check_clash(self.info, seen) qtype =3D v.type.alternate_qtype() if not qtype: @@ -700,7 +701,7 @@ def check(self, schema: QAPISchema) -> None: def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc - for v in self.alternatives.variants: + for v in self.alternatives: v.connect_doc(doc) =20 def c_type(self) -> str: @@ -726,6 +727,9 @@ def __init__( self.tag_member: QAPISchemaObjectTypeMember self.variants =3D variants =20 + def __iter__(self) -> Iterator[QAPISchemaVariant]: + return iter(self.variants) + def set_defined_in(self, name: str) -> None: for v in self.variants: v.set_defined_in(name) diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py index 0dd0b00ada3..ad36b55488f 100644 --- a/scripts/qapi/types.py +++ b/scripts/qapi/types.py @@ -166,7 +166,7 @@ def gen_object(name: str, ifcond: QAPISchemaIfCond, objects_seen.add(name) =20 ret =3D '' - for var in variants.variants if variants else (): + for var in variants or (): obj =3D var.type if not isinstance(obj, QAPISchemaObjectType): continue @@ -234,7 +234,7 @@ def gen_variants(variants: QAPISchemaVariants) -> str: ''', c_name=3Dc_name(variants.tag_member.name)) =20 - for var in variants.variants: + for var in variants: if var.type.name =3D=3D 'q_empty': continue ret +=3D var.ifcond.gen_if() diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py index 12f92e429f6..1eca452378c 100644 --- a/scripts/qapi/visit.py +++ b/scripts/qapi/visit.py @@ -141,7 +141,7 @@ def gen_visit_object_members(name: str, ''', c_name=3Dc_name(tag_member.name)) =20 - for var in branches.variants: + for var in branches: case_str =3D c_enum_const(tag_member.type.name, var.name, tag_member.type.prefix) ret +=3D var.ifcond.gen_if() @@ -246,7 +246,7 @@ def gen_visit_alternate(name: str, ''', c_name=3Dc_name(name)) =20 - for var in alternatives.variants: + for var in alternatives: ret +=3D var.ifcond.gen_if() ret +=3D mcgen(''' case %(case)s: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797561; cv=none; d=zohomail.com; s=zohoarc; b=Lidqi1ru62Yw1brkHOkM/DxCp0jTsQuLkRZS7ExRZ76//R+yfRgPk7oiLhzl/1TFa5Fnbcj+u/LEVBvLDJFxf45GstdUdl5+asd0RW4lylJ8P8SO+K8Fb3H6v6NS9F0p+EPcR8FINvHcqx0wLnbrHervNAo0wAB8/j/oYJa5dl4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797561; 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=OG1OMNHyw6wL72+on5pGRFR4/JQLepCqy5ztn8vdu08=; b=f6JKTxBqBvy92XwJMwDS4K0AXWNudTpx51neiQlwJTyDI6TIRsdFeeMTbM0WsO3qiDu2xt0bX7tGhAsWHeoyL++f9mXz7sQimGuixzwLY2ATlKNUUtwM3V/25Fr2Dbqv7+6J1eVIJg13/l0Dxirxn7htaVNrEK8dDiANhY6JrMQ= 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 1738797561339280.3521454183166; Wed, 5 Feb 2025 15:19:21 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodH-0003oS-Jr; Wed, 05 Feb 2025 18:16:36 -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 1tfod8-00031d-Vq for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:28 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfod2-0006YT-3D for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:26 -0500 Received: from mx-prod-mc-01.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-377-O5dzuOe0MomKpZp09rTSxA-1; Wed, 05 Feb 2025 18:16:11 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 00803195608C; Wed, 5 Feb 2025 23:16:10 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 640A81800570; Wed, 5 Feb 2025 23:16:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797372; 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=OG1OMNHyw6wL72+on5pGRFR4/JQLepCqy5ztn8vdu08=; b=gDUqFW9nCznvtH3pAGpPxUJQogWItclU9XMMe/k/Hd74Y72xZZIWCIjaNxSGVWFYweNUSY a2O7dzxvgPhqsGfRIaw0FpA7wXBxQCNGmc+3vnbzP3VsTlJwPMZtwa9UsQLTN8kRMGyqK5 aFWmaUhLh5iarvz8UVgJtIKhX65P8B0= X-MC-Unique: O5dzuOe0MomKpZp09rTSxA-1 X-Mimecast-MFC-AGG-ID: O5dzuOe0MomKpZp09rTSxA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 38/42] docs/qapi: add branch support to inliner Date: Wed, 5 Feb 2025 18:12:04 -0500 Message-ID: <20250205231208.1480762-39-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797564631019100 Content-Type: text/plain; charset="utf-8" Well, kind of. Anything beyond simple member definitions aren't included; including ifcond, details sections, features, etc. Definitely the most "WIP" part of this entire patch series. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 57 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 755eb0fa0ec..86c13520d94 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -44,6 +44,7 @@ from qapi.schema import ( QAPISchema, QAPISchemaArrayType, + QAPISchemaBranches, QAPISchemaCommand, QAPISchemaEntity, QAPISchemaEnumMember, @@ -68,6 +69,20 @@ logger =3D logging.getLogger(__name__) =20 =20 +# These classes serve as pseudo-sections that this generator uses to +# flatten and inline arg sections from multiple entities. +class BranchStart(QAPIDoc.Section): + def __init__(self, key: str, value: str, info: QAPISourceInfo): + super().__init__(info, QAPIDoc.Kind.META) + self.key =3D key + self.value =3D value + + +class BranchEnd(QAPIDoc.Section): + def __init__(self, info: QAPISourceInfo): + super().__init__(info, QAPIDoc.Kind.META) + + def dedent(text: str) -> str: # Adjust indentation to make description text parse as paragraph. =20 @@ -105,6 +120,7 @@ def categorize(section: QAPIDoc.Section) -> "Optional[D= ocRegion]": QAPIDoc.Kind.SINCE: None, QAPIDoc.Kind.TODO: None, QAPIDoc.Kind.DETAIL: DocRegion.DETAIL, + QAPIDoc.Kind.META: DocRegion.MEMBER, } =20 =20 @@ -226,6 +242,15 @@ def _get_inline_target( return ent.base return None =20 + def _variants(ent) -> Optional[QAPISchemaBranches]: + if isinstance(ent, QAPISchemaObjectType): + return ent.branches + return None + + def _memb_filter(sec: QAPIDoc.Section) -> bool: + # meta grabs branch start/end markers, too. + return sec.kind in (QAPIDoc.Kind.MEMBER, QAPIDoc.Kind.META) + # Let's do this thing! =20 if ent is None: @@ -241,7 +266,22 @@ def _get_inline_target( # Now, stitch the results together! sections.absorb(inlined) =20 - # FIXME: Branches should be handled about here O:-) + # Now, pick up member sections from branches, if any. + # FIXME: Anything other than members are unhandled/ignored here...! + branch_sections =3D [] + if variants :=3D _variants(ent): + for variant in variants.variants: + branch_sections.append( + BranchStart( + variants.tag_member.name, variant.name, variants.info + ) + ) + var_sections =3D inline(variant.type) + branch_sections.extend(filter(_memb_filter, var_sections)) + branch_sections.append(BranchEnd(variants.info)) + + # Inject branches *after* the member section. + sections.partitions[DocRegion.MEMBER].extend(branch_sections) =20 # Pseudo-feature: document the OOB property. if isinstance(ent, QAPISchemaCommand) and ent.allow_oob: @@ -485,6 +525,21 @@ def visit_sections(self, ent: QAPISchemaEntity) -> Non= e: =20 # Add sections *in the order they are documented*: for section in sections: + if isinstance(section, BranchStart): + self.ensure_blank_line() + self.add_line( + f".. qapi:branch:: {section.key} {section.value}", + section.info, + ) + self.ensure_blank_line() + self.indent +=3D 1 + continue + + if isinstance(section, BranchEnd): + self.ensure_blank_line() + self.indent -=3D 1 + continue + if section.kind.name in ("INTRO", "DETAIL"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797522; cv=none; d=zohomail.com; s=zohoarc; b=IAHLZ5gCgLyemnTrRyPS5AwXY5lZ2cnDEhjdZj0ZB8KkWgGOsO2VHDNmfGd3+zwCKDNkyxant31GdBNmD8HB9bJG44HhUYMoGH4kwEPPSoBfcVtKnRsEklhuq3NjYsxLFgWvNrponkvvzrQOi7UCyjxOw4JyK0W+x2ijnSC1fpk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797522; 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=lgAoyiNttGPvLvdaSWO3C5jznH7saF5lZMYoMJ8yOy4=; b=aSiGmui3oFHRbEjnzwdxH5QFEAAHg3lSRQfp9z5vzNFBuxKQ99Vh0vXra630G0J5CZj2NEsnSJAvpMePSypvHmh5f1V0S9BYRWykhBIqFQGu/OUYSENq4YsuQUJcFRIpHKv9sGTEaF5xtprsKTItE6lxflJaHTXUMi9i7iQ0KGY= 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 173879752297392.06017205478543; Wed, 5 Feb 2025 15:18:42 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodG-0003j9-Jr; Wed, 05 Feb 2025 18:16:34 -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 1tfodA-00032R-AE for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:28 -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 1tfod7-0006Zk-2S for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:28 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-324-ZOjw777cMLWMlDqXAr5Epg-1; Wed, 05 Feb 2025 18:16:18 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1E40D1800268; Wed, 5 Feb 2025 23:16:16 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 446541800570; Wed, 5 Feb 2025 23:16:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797379; 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=lgAoyiNttGPvLvdaSWO3C5jznH7saF5lZMYoMJ8yOy4=; b=UNdsoSIRAxUKV2SWr3k604JOLUHKIAQfGPr8MZpZXo+71UAxxwAmU6pWhVEkNze8FOB5LV Oe9PMTHXGDsuOfC+CSIzKFb0boLBXUBgh4s9ECtMqzApgCERw88jnRwynwCmQ+GCP98n+M VZYm7thiNphM6h9S2ncNpBgzIqQB5Hw= X-MC-Unique: ZOjw777cMLWMlDqXAr5Epg-1 X-Mimecast-MFC-AGG-ID: ZOjw777cMLWMlDqXAr5Epg From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 39/42] qapi/schema: add doc_visible property to QAPISchemaDefinition Date: Wed, 5 Feb 2025 18:12:05 -0500 Message-ID: <20250205231208.1480762-40-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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=0.001, 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: 1738797524540019100 Content-Type: text/plain; charset="utf-8" This patch adds a boolean flag to mark definitions as "visible" in the end-user HTML docs. The intent is that definitions that are not marked as visible will not be rendered. What gets marked visible? The short version: all commands and events are inherently visible. All other definitions are visible if and only if they are the target of a cross-reference in the generated output. The long version: - All commands: - All arg_type members, excluding arg_type itself (because it's inlined) - All ret_type members, *including* ret_type itself (because we cross-reference the return type) - All events: - All arg_type members, excluding arg_type itself (because it's inlined) - For any object marked visible by the above; - All members (which includes inherited members) - All branch objects, excluding the branch object itself (because the branches are inlined) - For any array marked visible by the above; - The array itself, and - The contained element_type - For any alternate marked visible by the above; - The alternate itself, and - All of its branch types. (because we don't currently inline anything for alternates.) All other definitions are not doc_visible; those exclusions are: - Any definition not recursively referenced by any command or event; i.e. definitions used internally by QEMU but not actually used by the QMP protocol. - Any definition used only as an arg_type for events or commands; because the doc generator inlines arguments, there is no need to generate documentation for the arguments/members by themselves. - Any definition used only as a base_type for objects. The new doc generator will inline inheritance, so there is no need to generate standalone documentation for factored/common objects. - Any definition used only as a branch type for a union. The new doc generator also inlines branch members as it does for local and inherited members, so there's no need to document each branch as a standalone entity. Note that if a type is used both in an "inlined" context and a "referenced" context, documentation *will* be generated for that type; e.g. a struct type used both as a base_type *and* as a member argument. This does not necessarily match the data revealed by the runtime introspection feature: in the generated documentation case, we want anything that we are cross-referencing in generated documentation to be available to target with cross-reference syntax. Some built-in types may be marked visible with this approach, but if they do not have a documentation block, they'll be skipped by the generator anyway. This includes array types and built-in primitives which do not get their own documentation objects. i.e., for documentation to be generated for a given QAPISchemaDefinition in the new generator, it must have non-empty documentation AND be doc_visible. This differs from the current qapidoc generator which only requires non-empty documentation. This means some items marked doc_visible *still* will not be rendered because they lack documentation to render. This information is not yet used by the current generator, which continues to render documentation exactly as it has. This information will be used by the new qapidoc (the "transmogrifier") in the next commit. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/schema.py | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index 4c55f7640b6..32c9a8f4cd2 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -131,6 +131,7 @@ def __init__( self.doc =3D doc self._ifcond =3D ifcond or QAPISchemaIfCond() self.features =3D features or [] + self.doc_visible =3D False =20 def __repr__(self) -> str: return "<%s:%s at 0x%x>" % (type(self).__name__, self.name, @@ -146,6 +147,10 @@ def check(self, schema: QAPISchema) -> None: for f in self.features: f.check_clash(self.info, seen) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + if mark_self: + self.doc_visible =3D True + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -483,6 +488,10 @@ def check(self, schema: QAPISchema) -> None: self.info.defn_meta if self.info else None) assert not isinstance(self.element_type, QAPISchemaArrayType) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + self.element_type.mark_visible() + def set_module(self, schema: QAPISchema) -> None: self._set_module(schema, self.element_type.info) =20 @@ -607,6 +616,17 @@ def connect_doc(self, doc: Optional[QAPIDoc] =3D None)= -> None: for m in self.local_members: m.connect_doc(doc) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + # Mark this object and its members as visible in the user-facing d= ocs. + if self.doc_visible: + return + + super().mark_visible(mark_self) + for m in self.members: + m.type.mark_visible() + for var in self.branches or []: + var.type.mark_visible(False) + def is_implicit(self) -> bool: # See QAPISchema._make_implicit_object_type(), as well as # _def_predefineds() @@ -698,6 +718,11 @@ def check(self, schema: QAPISchema) -> None: % (v.describe(self.info), types_seen[qt])) types_seen[qt] =3D v.name =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + for var in self.alternatives: + var.type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1056,6 +1081,13 @@ def check(self, schema: QAPISchema) -> None: "command's 'returns' cannot take %s" % self.ret_type.describe()) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + if self.ret_type: + self.ret_type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1112,6 +1144,11 @@ def check(self, schema: QAPISchema) -> None: self.info, "conditional event arguments require 'boxed': true") =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1488,6 +1525,9 @@ def check(self) -> None: ent.set_module(self) for doc in self.docs: doc.check() + for ent in self._entity_list: + if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)): + ent.mark_visible() =20 def visit(self, visitor: QAPISchemaVisitor) -> None: visitor.visit_begin(self) --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797423; cv=none; d=zohomail.com; s=zohoarc; b=W87oXU8iMNRku25sF4H2aryXthUwE8oOhxT82i0c1gIcsIunHcUn7wtQ6byCDD4CHxPbUAFAXINOC/9jct9o5lh5sii7gqx7mQtKFvBjXNnYd/o+4mDKVPd42NqX11gILbK/pgzRcvvMQYWiQER1Im2gCL8uos+XTtnQbewrwIM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797423; 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=t/9paVO1pxyYJ28kkMcOqfaSWRKUzMpG7ObtwDsDFz4=; b=kYczuoPcKUi2v6myzew6ESK5HM9nbaeObEUQSStN6zPFpNs907K3ToAx+wQNiSyFic2grVfD/cyHzCkZslGYhbBitJhvLliAMH4i8U5vcId9GMkM82KvdXSGMaQtdFl0Vjuog3QyhSdipevBBOaBSC0TVQDuUsf2fYbVpkdZCBM= 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 1738797423156393.3909791695046; Wed, 5 Feb 2025 15:17:03 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodL-0004H7-WD; Wed, 05 Feb 2025 18:16:40 -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 1tfodA-00032S-Cn for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:28 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfod8-0006cR-PG for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:28 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-327-i4VCLBLQOO6UrHVfXJVynA-1; Wed, 05 Feb 2025 18:16:24 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0DB9C1800981; Wed, 5 Feb 2025 23:16:23 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8EC9D1800570; Wed, 5 Feb 2025 23:16:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797386; 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=t/9paVO1pxyYJ28kkMcOqfaSWRKUzMpG7ObtwDsDFz4=; b=ebaQuPNCEXx37rp9o+KiS4QjHryuGvTPF5aWybi8OvCxCxMQCDCssXkwMS6tOf7LfudKew I1YT76uHgYkstH+MXVqumnZeAYbtt4R8J2FTeoySfAaRj2ZB1o0LrrYrBb7R5nEdRUHDku t/n/jntHsWhjTAg1QhVPmAvbkyOlNHE= X-MC-Unique: i4VCLBLQOO6UrHVfXJVynA-1 X-Mimecast-MFC-AGG-ID: i4VCLBLQOO6UrHVfXJVynA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 40/42] docs/qapidoc: cull (most) un-named entities from docs Date: Wed, 5 Feb 2025 18:12:06 -0500 Message-ID: <20250205231208.1480762-41-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797431601019000 Content-Type: text/plain; charset="utf-8" This patch excludes any items not marked visible from the transmogrifier output. The legacy qapidoc mechanism continues to ignore this flag, so the existing docs are not effected. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 86c13520d94..e7da5b2225f 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -616,6 +616,13 @@ def visit_freeform(self, doc) -> None: def visit_entity(self, ent): assert ent is not None =20 + # Some entities need not be rendered; they are not exposed via + # introspection and are only relevant for purposes of + # inlining/inheritance. They don't need their own entries and + # don't need to be in the index. + if not ent.doc_visible: + return + try: self._curr_ent =3D ent # This line gets credited to the start of the /definition/. --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797552; cv=none; d=zohomail.com; s=zohoarc; b=gPUi3X2pPsFX+BV7ke+VbAYJvXcS88Ze4E5AYjD3LJBng+fUHSuWSsL+Sw0wBkaSvHTuaDQP1008r5gXHZIoZVb5ouRDCjVV9aSrgArR5+RB86GROXkYUGfUGpgYlI4yrNjZlscvCUmjOD2P/6nCU37JHq27mmZsMuw1k+DjIis= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797552; 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=6dUMEjpaEojRHmw1zhCPih5WRmh1AZiaK1PMPnsNsm4=; b=BOlo+Crx4XB5fOhligk4yyHmwZBrcfJ5GLuArONDn5+01WXo1fSFJnnuWQ+IASmESV1/MDFjpMjAt6e7y2kI7iUeyeGoDQNf78Tt8aSo32RhCaegkpVzioNffvD+svKzpqubMTWZjJXkqTDqThXJz5bGWovupQDRLwJqfVJaVHs= 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 1738797552669606.165579380247; Wed, 5 Feb 2025 15:19:12 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodO-0004OW-7Z; Wed, 05 Feb 2025 18:16:42 -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 1tfodJ-00047j-JZ for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:37 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfodH-0006dM-ST for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:37 -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-693-hMp7g_RWNXKOHiVdTvErkA-1; Wed, 05 Feb 2025 18:16:31 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 1F0091956088; Wed, 5 Feb 2025 23:16:30 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 782DE1800570; Wed, 5 Feb 2025 23:16:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797394; 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=6dUMEjpaEojRHmw1zhCPih5WRmh1AZiaK1PMPnsNsm4=; b=ReixSoxyU7+CaRYvQTaJULtxslViP1yhWoIk6IYJOVFTqIGN9Zyl38wdeUi2Ci2XNhX902 1TGITALUWm9D59ldlm+M8wb749eqxrfvclr12QasjCmy1b0YM66EBYvrs8BNpECbU7vsxp th7SBgIbONqk7yKit/t0R3MJgkve0XU= X-MC-Unique: hMp7g_RWNXKOHiVdTvErkA-1 X-Mimecast-MFC-AGG-ID: hMp7g_RWNXKOHiVdTvErkA From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 41/42] qapi: resolve filenames in info structures Date: Wed, 5 Feb 2025 18:12:07 -0500 Message-ID: <20250205231208.1480762-42-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797554510019100 Content-Type: text/plain; charset="utf-8" Resolve symbolic filenames (i.e. build/../tests/qapi-schema) to fully specified absolute paths in QAPI info structures. Normalizing filenames in this way makes trimming common path prefixes for test output more consistent. It's also used for the intermediate output representation for the new transmogrifier. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- scripts/qapi/parser.py | 3 ++- tests/qapi-schema/test-qapi.py | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c92bbc908e7..76fac70c477 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -17,6 +17,7 @@ from collections import OrderedDict import enum import os +from pathlib import Path import re from typing import ( TYPE_CHECKING, @@ -100,7 +101,7 @@ def __init__(self, self.src =3D '' =20 # Lexer state (see `accept` for details): - self.info =3D QAPISourceInfo(self._fname, incl_info) + self.info =3D QAPISourceInfo(str(Path(self._fname).resolve()), inc= l_info) self.tok: Union[None, str] =3D None self.pos =3D 0 self.cursor =3D 0 diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index bca924309be..27324d53850 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -15,6 +15,7 @@ import argparse import difflib import os +from pathlib import Path import sys from io import StringIO =20 @@ -216,6 +217,7 @@ def main(argv): (dir_name, base_name) =3D os.path.split(t) dir_name =3D dir_name or args.dir test_name =3D os.path.splitext(base_name)[0] + dir_name =3D str(Path(dir_name).resolve()) status |=3D test_and_diff(test_name, dir_name, args.update) =20 sys.exit(status) --=20 2.48.1 From nobody Sat Feb 7 06:57:32 2026 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=1738797451; cv=none; d=zohomail.com; s=zohoarc; b=Hv2JHawAiTRIZmHwIOTc6jBld6t9OBwYt1zI0ew5xZjgQiin3RX7U2rLyhvrvLMnS7XyQwIHaTXXV0X/NO7k+TAsDzZna6caaVuL0aOg+V8X76qLBoixy4S/VZGA4ka7VeDkgX5l1WXnwLrG8pR6tZ+PEunriPmLfaxOG4+XpAs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1738797451; 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=QJyts+XObo7CJGUMCjTABmQ6SpbjxdYyosgm/niuzRo=; b=b/si+vUmQYZWCLOYW9nFJCVaMXvmCP/9s9E26Gt7i6jMfUdZA+rMoEt6NxjkmkzPFyQGdg6GdXRAbsv/mBT2KPANiCLE732uRL0O/2YmfnJVBXxMF1/bCRYnjJtjB7DVv5PSlKOsvwQ+5R8uLYPkjTavG+jvhbPPpJzWoFL18S8= 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 173879745135144.20993753964558; Wed, 5 Feb 2025 15:17:31 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tfodT-0004g9-Ht; Wed, 05 Feb 2025 18:16:47 -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 1tfodQ-0004ZH-1j for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:44 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tfodO-0006e5-5m for qemu-devel@nongnu.org; Wed, 05 Feb 2025 18:16:43 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-475-5v7oEv1YPI61VazQgRzy1A-1; Wed, 05 Feb 2025 18:16:38 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7F4C41800875; Wed, 5 Feb 2025 23:16:36 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.104]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 63EC41800570; Wed, 5 Feb 2025 23:16:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1738797401; 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=QJyts+XObo7CJGUMCjTABmQ6SpbjxdYyosgm/niuzRo=; b=QjNtSfjofwrVGzPCqUeBdN2M81h2LL07fJkrCN2qdIgaooEaJfT1MmSVFcAbA5TeL2tVdl 7Qie/jghkY9sdq88bjFAaUnVCIsnoD6OOH99ucUdSdHGO9BLzshdyTXyWnD7KZNoHxNeKf hZ5rpT+GE6vFUbg+gPra4NS9iwRfibM= X-MC-Unique: 5v7oEv1YPI61VazQgRzy1A-1 X-Mimecast-MFC-AGG-ID: 5v7oEv1YPI61VazQgRzy1A From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , Thomas Huth , Yanan Wang , Fabiano Rosas , Zhao Liu , Lukas Straub , Eduardo Habkost , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Eric Blake , Marcel Apfelbaum , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Jason Wang , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH 42/42] docs/qapidoc: add intermediate output debugger Date: Wed, 5 Feb 2025 18:12:08 -0500 Message-ID: <20250205231208.1480762-43-jsnow@redhat.com> In-Reply-To: <20250205231208.1480762-1-jsnow@redhat.com> References: <20250205231208.1480762-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: 1738797454233019100 Content-Type: text/plain; charset="utf-8" Add debugging output for the qapidoc transmogrifier - setting DEBUG=3D1 will produce .ir files (one for each qapidoc directive) that write the generated rst file to disk to allow for easy debugging and verification of the generated document. Signed-off-by: John Snow based-on: https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.co= m/ --- docs/sphinx/qapidoc.py | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index e7da5b2225f..7b895c3668e 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -36,7 +36,7 @@ from typing import Dict, List, Optional =20 from docutils import nodes -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import directives from docutils.statemachine import StringList, ViewList from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor @@ -60,7 +60,7 @@ from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util import logging -from sphinx.util.docutils import switch_source_input +from sphinx.util.docutils import SphinxDirective, switch_source_input from sphinx.util.nodes import nested_parse_with_titles =20 =20 @@ -1053,7 +1053,7 @@ def visit_module(self, name): super().visit_module(name) =20 =20 -class NestedDirective(Directive): +class NestedDirective(SphinxDirective): def run(self): raise NotImplementedError =20 @@ -1122,10 +1122,43 @@ def transmogrify(self, schema) -> nodes.Element: node.document =3D self.state.document self.state.nested_parse(content, 0, contentnode) logger.info("Transmogrifier's nested parse completed.") + + if self.env.app.verbosity >=3D 2 or os.environ.get("DEBUG"): + argname =3D "_".join(Path(self.arguments[0]).parts) + name =3D Path(argname).stem + ".ir" + self.write_intermediate(content, name) + sys.stdout.flush() - return contentnode =20 + def write_intermediate(self, content, filename): + logger.info( + "writing intermediate rST for '%s' to '%s'", + self.arguments[0], + filename, + ) + + srctree =3D Path(self.env.app.config.qapidoc_srctree).resolve() + outlines =3D [] + lcol_width =3D 0 + + for i, line in enumerate(content): + src, lineno =3D content.info(i) + src =3D Path(src).resolve() + src =3D src.relative_to(srctree) + + lcol =3D f"{src}:{lineno:04d}" + lcol_width =3D max(lcol_width, len(lcol)) + outlines.append((lcol, line)) + + with open(filename, "w", encoding=3D"UTF-8") as outfile: + for lcol, rcol in outlines: + outfile.write(lcol.rjust(lcol_width)) + outfile.write(" |") + if rcol: + outfile.write(f" {rcol}") + outfile.write("\n") + def legacy(self, schema) -> nodes.Element: vis =3D QAPISchemaGenRSTVisitor(self) vis.visit_begin(schema) --=20 2.48.1