From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146433; cv=none; d=zohomail.com; s=zohoarc; b=P0M0Pmk3wcILhY4Rxacs/uLZabJoLpyjhwsGgB2jYas8oEcp7JQUm9Z2MyuowNXXchZfO84+F7TSB+FxyTbwqqfbtXawRD1HKSeaARTtiDsZ8c3kDf032+4mh/v/DJpuv+IQqSsjyAtW9iNBS+8+6XR5yqFekDMbLy3GWVRbCg0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146433; 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=HSTcrgIm/gu5mC8r1knFzmlq8huuqEckgCBNTahOciY=; b=gjiCZ7/vBnc+jVhSsZvZqK+aSSjJxNTW42WsCkBbipgemXCJ5eN5CnTILwIso+9hRDAHaD7G1nfjIoV1jnBOM6LlaSXNCl7B3K3Myth0hI9yvZ/JgJ0f2XcTKMGJ4YcxR7EzfUx14NWsYiQAV4GKVlYtihwqlRuDf8zoqkI8tso= 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 1741146433450864.5614842392215; Tue, 4 Mar 2025 19:47:13 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfiH-0005KP-De; Tue, 04 Mar 2025 22:46: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 1tpfiF-0005KB-MR for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46: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 1tpfiD-0005zs-VK for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:27 -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-500-2WtA5FHHM1KG2t0HGj1LhA-1; Tue, 04 Mar 2025 22:46:20 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 A811B180025E; Wed, 5 Mar 2025 03:46:19 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D9A961956095; Wed, 5 Mar 2025 03:46:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146382; 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=HSTcrgIm/gu5mC8r1knFzmlq8huuqEckgCBNTahOciY=; b=e073VoBra/+6BmQrXdGoxuVNXtrCz/omAMrAWC9x2FO+wrUsooItQKb9VyKVOzhdyXQdJG ruLsxeWasoyHy4q/gpu/nOG/FsAxK42Mv1TrJewwDVSbL2RZqtBSDcMhDZUEe6VVMoKxS6 BqlLhOfaNG23XzEU4ONZqZ81UqFECns= X-MC-Unique: 2WtA5FHHM1KG2t0HGj1LhA-1 X-Mimecast-MFC-AGG-ID: 2WtA5FHHM1KG2t0HGj1LhA_1741146379 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 01/57] do-not-merge Date: Tue, 4 Mar 2025 22:45:10 -0500 Message-ID: <20250305034610.960147-2-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146434569019100 Content-Type: text/plain; charset="utf-8" Ad-hoc linting scripts to scrub down the new docs/sphinx files. Should work with a reasonably modern mypy/pylint/etc, and Sphinx 8.2.0. Older versions of Sphinx ought to still work at runtime, but may not type check correctly. Signed-off-by: John Snow --- scripts/qapi-lint.sh | 55 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100755 scripts/qapi-lint.sh diff --git a/scripts/qapi-lint.sh b/scripts/qapi-lint.sh new file mode 100755 index 00000000000..0e3ff002b69 --- /dev/null +++ b/scripts/qapi-lint.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +set -e + +if [[ -f qapi/.flake8 ]]; then + echo "flake8 --config=3Dqapi/.flake8 qapi/" + flake8 --config=3Dqapi/.flake8 qapi/ +fi +if [[ -f qapi/pylintrc ]]; then + echo "pylint --rcfile=3Dqapi/pylintrc qapi/" + pylint --rcfile=3Dqapi/pylintrc qapi/ +fi +if [[ -f qapi/mypy.ini ]]; then + echo "mypy --config-file=3Dqapi/mypy.ini qapi/" + mypy --config-file=3Dqapi/mypy.ini qapi/ +fi + +if [[ -f qapi/.isort.cfg ]]; then + pushd qapi + echo "isort -c ." + isort -c . + popd +fi + +if [[ -f ../docs/sphinx/qapi_domain.py ]]; then + files=3D"qapi_domain.py" +fi +if [[ -f ../docs/sphinx/compat.py ]]; then + files=3D"${files} compat.py" +fi +if [[ -f ../docs/sphinx/collapse.py ]]; then + files=3D"${files} collapse.py" +fi + +if [[ -f ../docs/sphinx/qapi_domain.py ]]; then + pushd ../docs/sphinx + + set -x + mypy --strict $files + flake8 --max-line-length=3D80 $files qapidoc.py + isort -c $files qapidoc.py + black --line-length 80 --check $files qapidoc.py + PYTHONPATH=3D../../scripts/ pylint \ + --rc-file ../../scripts/qapi/pylintrc \ + $files qapidoc.py + set +x + + popd +fi + +pushd ../build +make -j13 +make check-qapi-schema +make docs +make sphinxdocs +popd --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146432; cv=none; d=zohomail.com; s=zohoarc; b=IJTrHMwfHFvW9BlzrDz7iytpamsWBA5sRyV3kjt5juHP5eFVYCUA3mpR15deDXB7oXOxgVsJSnexWkjSo1Bmew721Jm2Dum3zBlhBuaADDHPjWYp2a87V6iRueAlt3vhuw7eLksrpzIn9yNYeqpxNU6ydych8UMxkYpD3qRV8uw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146432; 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=EIxtKIfXAperan5ep4E1FQ8USyNb2fZLbeC2CWp4A+k=; b=luY2hoRkto11wCXCc8REKoaZFXd9CQXx1Vf1KqHsuWbJzHvvxizkAHS3Dnr5uiMpjIlFMNFoeuFcVCMmmTKQZXLH0ZKDVhuRGv6k0R9bDyvHuP+6dBTHiOD+O8fHwT36+aYyEVq4KTBxVLodTkd9wcelKMTdy2Tdnxkp2GuSvsc= 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 174114643241185.2951210137661; Tue, 4 Mar 2025 19:47:12 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfiI-0005Ku-S0; Tue, 04 Mar 2025 22:46: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 1tpfiH-0005KQ-U1 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:29 -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 1tpfiG-00060J-CD for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:29 -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-607-7C41S4lHOHOsMFRH3qp0iw-1; Tue, 04 Mar 2025 22:46:24 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 80C8F1955D66; Wed, 5 Mar 2025 03:46:23 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4D8411956095; Wed, 5 Mar 2025 03:46:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146386; 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=EIxtKIfXAperan5ep4E1FQ8USyNb2fZLbeC2CWp4A+k=; b=RXpv9Ru5w/iVqXCNzugNFJDgHVDFyQLRLuKz5yRqVzqPbTplumElLiGCxnrB8S+EEDtDXq ICTP1WrAIk9ug/xOUp4NHKIUR/Ay8vRakzQo0WZ3WYmahgZ9EzJv5mJPBwQTEzcrbrwxgD nyA9h1nNanvkBA9kAyvmJNh+hwcnMIQ= X-MC-Unique: 7C41S4lHOHOsMFRH3qp0iw-1 X-Mimecast-MFC-AGG-ID: 7C41S4lHOHOsMFRH3qp0iw_1741146383 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 02/57] qapi: shush pylint up Date: Tue, 4 Mar 2025 22:45:11 -0500 Message-ID: <20250305034610.960147-3-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146433417019000 Content-Type: text/plain; charset="utf-8" Shhhhh! This patch is RFC quality, I wasn't in the mood to actually solve problems so much as I was in the mood to continue working on the Sphinx rework. Plus, I don't think the code I am patching has hit origin/master yet ... Signed-off-by: John Snow --- scripts/qapi/backend.py | 2 ++ scripts/qapi/main.py | 10 ++++------ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/scripts/qapi/backend.py b/scripts/qapi/backend.py index 14e60aa67af..49ae6ecdd33 100644 --- a/scripts/qapi/backend.py +++ b/scripts/qapi/backend.py @@ -13,6 +13,7 @@ =20 =20 class QAPIBackend(ABC): + # pylint: disable=3Dtoo-few-public-methods =20 @abstractmethod def generate(self, @@ -36,6 +37,7 @@ def generate(self, =20 =20 class QAPICBackend(QAPIBackend): + # pylint: disable=3Dtoo-few-public-methods =20 def generate(self, schema: QAPISchema, diff --git a/scripts/qapi/main.py b/scripts/qapi/main.py index ff42b43cd68..01155373bd0 100644 --- a/scripts/qapi/main.py +++ b/scripts/qapi/main.py @@ -31,15 +31,14 @@ def create_backend(path: str) -> QAPIBackend: =20 module_path, dot, class_name =3D path.rpartition('.') if not dot: - print(f"argument of -B must be of the form MODULE.CLASS", + print("argument of -B must be of the form MODULE.CLASS", file=3Dsys.stderr) sys.exit(1) =20 try: mod =3D import_module(module_path) except Exception as ex: - print(f"unable to import '{module_path}': {ex}", file=3Dsys.stderr) - sys.exit(1) + raise QAPIError(f"unable to import '{module_path}': {ex}") from ex =20 try: klass =3D getattr(mod, class_name) @@ -51,9 +50,8 @@ def create_backend(path: str) -> QAPIBackend: try: backend =3D klass() except Exception as ex: - print(f"backend '{path}' cannot be instantiated: {ex}", - file=3Dsys.stderr) - sys.exit(1) + raise QAPIError( + f"backend '{path}' cannot be instantiated: {ex}") from ex =20 if not isinstance(backend, QAPIBackend): print(f"backend '{path}' must be an instance of QAPIBackend", --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146432; cv=none; d=zohomail.com; s=zohoarc; b=nnTcM3s7J+Bnr9o+L8NR+o1r0I022iACVgSurNbQEdnW3wfZOB0vjR4Ki/bGENPvRgPL+UAMGkieqKNJRF6jxKtomH4AKNt/7IJuBb7vb4cl7XNLCntnBuQ31FywUDA83PqcgmSskbNw/JBxIO80fGeCXmBWj7F5iWE3ec/LodU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146432; 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=MJ8i3B3IWUv9hwDYZ3ZSUdrZb/ZBpQUf3O+dp/jYjMw=; b=Rjzcaf42xXmz6lgKDMf117aOFnbzcYrONoa9ZhnBUaWFQzB1VQSOO+pFCSEWCn8uKsAjWYGIGcPRZ9QjDnNDBnFFnI/tCe97++5mysHQO7L7XYsHxCDmf2pCkMLIhdk06ExpmvZV/PjL1xOsTwahUhVEx+GOSWx9/FBesYiVjoQ= 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 1741146432677799.0237748734784; Tue, 4 Mar 2025 19:47:12 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfib-0005P7-LN; Tue, 04 Mar 2025 22:46:49 -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 1tpfiX-0005O0-77 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:45 -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 1tpfiV-00062Y-6f for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:44 -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-324-xeOJpzt0PyOGHsjD6QAQcA-1; Tue, 04 Mar 2025 22:46:34 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 4D196193578F; Wed, 5 Mar 2025 03:46:27 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id CCFBB1956095; Wed, 5 Mar 2025 03:46:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146402; 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=MJ8i3B3IWUv9hwDYZ3ZSUdrZb/ZBpQUf3O+dp/jYjMw=; b=cvpcA9lN5l950s/7tWCGn1PuzPs1tWFn5HrQKUm6H0dvn9LmSDgT6nAXIWq5tIHzau6isX tFSGS8BSzxuoohkPN1Pwg1JMaqoqd+PvjOVQptLlpo/xDDD2HUpicsXEGe1RiWWoCXWdim fwwj62gw2V7G/gjbKhCzo2xPoEo6FNo= X-MC-Unique: xeOJpzt0PyOGHsjD6QAQcA-1 X-Mimecast-MFC-AGG-ID: xeOJpzt0PyOGHsjD6QAQcA_1741146393 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 03/57] docs/sphinx: create QAPI domain extension stub Date: Tue, 4 Mar 2025 22:45:12 -0500 Message-ID: <20250305034610.960147-4-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146434487019100 Content-Type: text/plain; charset="utf-8" A Sphinx domain is a collection of directive and role extensions meant to facilitate the documentation of a specific language. For instance, Sphinx ships with "python" and "cpp" domains. This patch introduces a stub for the "qapi" language domain. Please see https://www.sphinx-doc.org/en/master/usage/domains/index.html for more information. This stub doesn't really do anything yet, we'll get to it brick-by-brick in the forthcoming commits to keep the series breezy and the git history informative. Signed-off-by: John Snow --- docs/conf.py | 9 +++++- docs/sphinx/qapi_domain.py | 56 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapi_domain.py diff --git a/docs/conf.py b/docs/conf.py index 31bb9a37893..49d9de894c0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,7 +60,14 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions =3D ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] +extensions =3D [ + 'depfile', + 'hxtool', + 'kerneldoc', + 'qapi_domain', + 'qapidoc', + 'qmp_lexer', +] =20 if sphinx.version_info[:3] > (4, 0, 0): tags.add('sphinx4') diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py new file mode 100644 index 00000000000..a1983d94440 --- /dev/null +++ b/docs/sphinx/qapi_domain.py @@ -0,0 +1,56 @@ +""" +QAPI domain extension. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + AbstractSet, + Any, + Dict, + Tuple, +) + +from sphinx.domains import Domain, ObjType +from sphinx.util import logging + + +if TYPE_CHECKING: + from sphinx.application import Sphinx + +logger =3D logging.getLogger(__name__) + + +class QAPIDomain(Domain): + """QAPI language domain.""" + + name =3D "qapi" + label =3D "QAPI" + + object_types: Dict[str, ObjType] =3D {} + directives =3D {} + roles =3D {} + initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D {} + indices =3D [] + + def merge_domaindata( + self, docnames: AbstractSet[str], otherdata: Dict[str, Any] + ) -> None: + pass + + def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any: + # pylint: disable=3Dunused-argument + return [] + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.setup_extension("sphinx.directives") + app.add_domain(QAPIDomain) + + return { + "version": "1.0", + "env_version": 1, + "parallel_read_safe": True, + "parallel_write_safe": True, + } --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146649; cv=none; d=zohomail.com; s=zohoarc; b=G91+mLVcSwFA8eE6yCW9N5Tzdvhs4Zwpbl+VblL55OLwFOzQpqJg1p2JI/YKtIiNJp6VR57R3fbDxjawzIRzD3vwIN/mDm7CEzGT3JSOrWMK7eLvjPA8BZQOMZ0vmvPLI0+Fop8WmNhUhn+IPADagZyaOd7tzW4ax0MS4+Q9sRI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146649; 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=T6TqtdK3QHiRBZKdssAAdRdFK6e5Ug2kJUSKKEhUJck=; b=Ctwc6dJ29+SOt813XHzV1MtMnFxeOOObW6xy1INqhlRuhUZEGJzHyuKHZbLTuto1rt7O+fpx8+idWBgiMEHCpZmkXhvGKyCMeC/Tv+vIwq20m1I6OOwL89N73JWRF9cScc0CoTkOsXq57qcFSCEm5Mau/UPSBvVXFIDRw9pyDd4= 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 1741146649414283.8238942304978; Tue, 4 Mar 2025 19:50:49 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfiX-0005O4-QL; Tue, 04 Mar 2025 22:46: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 1tpfiV-0005NU-1D for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:43 -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 1tpfiS-00061v-LQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:42 -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-64-EPb44TO7NkiK3dPlDAWejA-1; Tue, 04 Mar 2025 22:46:33 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 F2B7519039D0; Wed, 5 Mar 2025 03:46:29 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8D0A01955DDD; Wed, 5 Mar 2025 03:46:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146398; 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=T6TqtdK3QHiRBZKdssAAdRdFK6e5Ug2kJUSKKEhUJck=; b=hnCHjsmD3KwMJKygKlpYl74RTQ8wVL1wFlhgrVFm6heslnCRyyc+zPg5sT+deC6GIaz3mf oAbrrt9Jx28yqsHarAyBJPEK/O3nzzHSxqBBquaGWWAT3v38nFK87hhXFKJTkwdrrHXL4k 35gshWXp7XA8GC6q3Pb0cplnC4GRVkk= X-MC-Unique: EPb44TO7NkiK3dPlDAWejA-1 X-Mimecast-MFC-AGG-ID: EPb44TO7NkiK3dPlDAWejA_1741146390 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 04/57] docs/sphinx: add compat.py module and nested_parse helper Date: Tue, 4 Mar 2025 22:45:13 -0500 Message-ID: <20250305034610.960147-5-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146651495019000 Content-Type: text/plain; charset="utf-8" Create a compat module that handles sphinx cross-version compatibility issues. For the inaugural function, add a nested_parse() helper that handles differences in line number tracking for nested directive body parsing. Spoilers: there are more cross-version hacks to come throughout the series. Signed-off-by: John Snow --- docs/sphinx/compat.py | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/sphinx/compat.py diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py new file mode 100644 index 00000000000..792aca10e39 --- /dev/null +++ b/docs/sphinx/compat.py @@ -0,0 +1,33 @@ +""" +Sphinx cross-version compatibility goop +""" + +from docutils.nodes import Element + +from sphinx.util.docutils import SphinxDirective, switch_source_input +from sphinx.util.nodes import nested_parse_with_titles + + +def nested_parse(directive: SphinxDirective, content_node: Element) -> Non= e: + """ + This helper preserves error parsing context across sphinx versions. + """ + + # necessary so that the child nodes get the right source/line set + content_node.document =3D directive.state.document + + try: + # Modern sphinx (6.2.0+) supports proper offsetting for + # nested parse error context management + nested_parse_with_titles( + directive.state, + directive.content, + content_node, + content_offset=3Ddirective.content_offset, + ) + except TypeError: + # No content_offset argument. Fall back to SSI method. + with switch_source_input(directive.state, directive.content): + nested_parse_with_titles( + directive.state, directive.content, content_node + ) --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146715; cv=none; d=zohomail.com; s=zohoarc; b=XHjkkjnav/VIS31RKJC3csLDUQtY4WkgTs7cPiS3UdWR0xoYx4usanqhJhabPEJC8WeOd3rwResMUgI6gdlOnNGWujkZhz4obux9/2e1toAbnpaJjBXKtM42eB6z41GTHhaemLjP+mgU6Az6ZNfMe3d8u4biZnvZoKI8z28RgLM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146715; 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=Ng15VbEQRc/aE0mDvlp5ZprGwNkxrt0jH74IRQaoYcQ=; b=g2tIej0SAvHR3nU7QcgXN+ki6dz6sXSVoc0rq+vVEAEC6zcFcDV/F+5S3SfkPCyITQfsFyvhPBssSkIP6oqWHi8LrhmEvawkqjbH8BakEybJnpIuWPdB7x0kBV3+yEeG5Ft/CgsKPdaGsyZWP4Gnd01gC3tcHR3D8fg0WkyysqI= 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 1741146715961969.8291313102485; Tue, 4 Mar 2025 19:51:55 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfim-0005RI-W3; Tue, 04 Mar 2025 22:47:01 -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 1tpfik-0005Qe-Nc for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:58 -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 1tpfii-00064Z-7g for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:58 -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-619-TT1OfoijPbaruIlJsHNDuA-1; Tue, 04 Mar 2025 22:46:34 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 318D31954190; Wed, 5 Mar 2025 03:46:33 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 62B031955DDD; Wed, 5 Mar 2025 03:46:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146415; 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=Ng15VbEQRc/aE0mDvlp5ZprGwNkxrt0jH74IRQaoYcQ=; b=NMOPO3L6WAU8F8JDfkM4RDJ7zPSRToLahv+2dqgcuaTUUR5UlhLgtiHy6p97MbPT7Cqwnl xCg/yosC3aRu41prYlptfD7w8nxRxhYNIv2AzLd4FaTVz3pEH4lze7umZh1eiAPQM262iS 4hYph3dRYx/7Mc9EIdoHDN0631Bg/2I= X-MC-Unique: TT1OfoijPbaruIlJsHNDuA-1 X-Mimecast-MFC-AGG-ID: TT1OfoijPbaruIlJsHNDuA_1741146393 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 05/57] docs/qapi-domain: add qapi:module directive Date: Tue, 4 Mar 2025 22:45:14 -0500 Message-ID: <20250305034610.960147-6-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146717272019100 Content-Type: text/plain; charset="utf-8" This adds a qapi:module directive, which just notes the current module being documented and performs a nested parse of the content block, if present. This code is based pretty heavily on Sphinx's PyModule directive, but with unnecessary features excised. For example: .. qapi:module:: block-core Hello, and welcome to block-core! =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D lorem ipsum, dolor sit amet ... Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 107 ++++++++++++++++++++++++++++++++++++- 1 file changed, 106 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index a1983d94440..8ce3caf933d 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -8,20 +8,119 @@ TYPE_CHECKING, AbstractSet, Any, + ClassVar, Dict, + Iterable, + List, Tuple, + cast, ) =20 +from docutils import nodes +from docutils.parsers.rst import directives + +from compat import nested_parse +from sphinx import addnodes from sphinx.domains import Domain, ObjType from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective +from sphinx.util.nodes import make_id =20 =20 if TYPE_CHECKING: + from docutils.nodes import Element, Node + from sphinx.application import Sphinx + from sphinx.util.typing import OptionSpec =20 logger =3D logging.getLogger(__name__) =20 =20 +class QAPIModule(SphinxDirective): + """ + Directive to mark description of a new module. + + This directive doesn't generate any special formatting, and is just + a pass-through for the content body. Named section titles are + allowed in the content body. + + Use this directive to associate subsequent definitions with the + module they are defined in for purposes of search and QAPI index + organization. + + :arg: The name of the module. + :opt no-index: Don't add cross-reference targets or index entries. + :opt no-typesetting: Don't render the content body (but preserve any + cross-reference target IDs in the squelched output.) + + Example:: + + .. qapi:module:: block-core + :no-index: + :no-typesetting: + + Lorem ipsum, dolor sit amet ... + + """ + + has_content =3D True + required_arguments =3D 1 + optional_arguments =3D 0 + final_argument_whitespace =3D False + + option_spec: ClassVar[OptionSpec] =3D { + # These are universal "Basic" options; + # https://www.sphinx-doc.org/en/master/usage/domains/index.html#ba= sic-markup + "no-index": directives.flag, + "no-typesetting": directives.flag, + "no-contents-entry": directives.flag, # NB: No effect + # Deprecated aliases; to be removed in Sphinx 9.0 + "noindex": directives.flag, + "nocontentsentry": directives.flag, # NB: No effect + } + + def run(self) -> List[Node]: + modname =3D self.arguments[0].strip() + no_index =3D "no-index" in self.options or "noindex" in self.optio= ns + + self.env.ref_context["qapi:module"] =3D modname + + content_node: Element =3D nodes.section() + nested_parse(self, content_node) + + ret: List[Node] =3D [] + inode =3D addnodes.index(entries=3D[]) + + if not no_index: + node_id =3D make_id(self.env, self.state.document, "module", m= odname) + target =3D nodes.target("", "", ids=3D[node_id], ismod=3DTrue) + self.set_source_info(target) + self.state.document.note_explicit_target(target) + + indextext =3D f"QAPI module; {modname}" + inode =3D addnodes.index( + entries=3D[ + ("pair", indextext, node_id, "", None), + ] + ) + ret.append(inode) + content_node.insert(0, target) + + if "no-typesetting" in self.options: + if node_ids :=3D [ + node_id + for el in content_node.findall(nodes.Element) + for node_id in cast(Iterable[str], el.get("ids", ())) + ]: + target =3D nodes.target(ids=3Dnode_ids) + self.set_source_info(target) + ret.append(target) + else: + ret.extend(content_node.children) + + return ret + + class QAPIDomain(Domain): """QAPI language domain.""" =20 @@ -29,7 +128,13 @@ class QAPIDomain(Domain): label =3D "QAPI" =20 object_types: Dict[str, ObjType] =3D {} - directives =3D {} + + # Each of these provides a rST directive, + # e.g. .. qapi:module:: block-core + directives =3D { + "module": QAPIModule, + } + roles =3D {} initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D {} indices =3D [] --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146846; cv=none; d=zohomail.com; s=zohoarc; b=aS12fsAjLIrqv5rL9CuXspFG0Z5B9CgoLuGmPizzurqJoz97He6syD8O6SpIn9r79NglAsOpoGNxy8t8+8CA8M/aUzyJCVriXIdlH7tPPu79g1hATpytuUdUKJMtm0yddj4317oQs6PRJK0Zv0AXSxl17pMAUWPSu5zLa4a9z8U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146846; 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=ll7eEBHZmTf+wxXy0PnPmZ084Yv37EYEVaALXgrczEc=; b=jcMX1uQxzKgQ/hPmaIqydzRuFwNMbW7TiJdO/bZjKJrCpiWZvAmVgyzkU7AOzEEkxEKcvQO4ac6v36CRGP5Ep3igEM2lutQZpTpL9VBEifOZwG+iH73GMwbN/xZxXtH9+CJWjvzRhMuUlMD4YTrM/3df8fb8t7C6TnoFbMiPEqY= 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 1741146846572962.8560711058325; Tue, 4 Mar 2025 19:54:06 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfiZ-0005OJ-5P; Tue, 04 Mar 2025 22:46: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 1tpfiV-0005NV-1H for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:43 -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 1tpfiT-00062A-BN for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:42 -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-671-gn5YVELhNsabTpMWURxPQw-1; Tue, 04 Mar 2025 22:46:36 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 8E3601954190; Wed, 5 Mar 2025 03:46:35 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 793F41956095; Wed, 5 Mar 2025 03:46:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146399; 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=ll7eEBHZmTf+wxXy0PnPmZ084Yv37EYEVaALXgrczEc=; b=QALFHnsJpoBYb/GDoY7bhrtVc+i4946cWb3nUYM5Yf+PVwmpFnkIOMTkV6NkQqcWLWCs3J 1Y/37GMoeVsWs15DC9iX4zbewcI21LMqdO8L/n9CPPaGEUfVCzlUmd2cKG0+S7OSwn5vGo oEtu92WvUD7R/8+0PWJlW9ooOD5P+08= X-MC-Unique: gn5YVELhNsabTpMWURxPQw-1 X-Mimecast-MFC-AGG-ID: gn5YVELhNsabTpMWURxPQw_1741146395 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 06/57] docs/qapi-domain: add QAPI domain object registry Date: Tue, 4 Mar 2025 22:45:15 -0500 Message-ID: <20250305034610.960147-7-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146848184019000 Content-Type: text/plain; charset="utf-8" This is the first step towards QAPI domain cross-references and a QAPI reference index. This patch just creates the object registry and amends the qapi:module directive to use that registry. Update the merge_domaindata stub method now that we have actual data we may need to merge. This patch also defines that "module" entities can be referenced with :qapi:mod:`foo` or :qapi:any:`foo` references, although the implementation for those roles is handled in a forthcoming patch. Note that how to handle merge conflict resolution is unhandled, as the Sphinx python domain itself does not handle it either. I do not know how to intentionally trigger it, so I've left an assertion instead if it should ever come up ... Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 81 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 8ce3caf933d..b17fcb93f24 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -12,6 +12,7 @@ Dict, Iterable, List, + NamedTuple, Tuple, cast, ) @@ -22,6 +23,7 @@ from compat import nested_parse from sphinx import addnodes from sphinx.domains import Domain, ObjType +from sphinx.locale import _, __ from sphinx.util import logging from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id @@ -36,6 +38,13 @@ logger =3D logging.getLogger(__name__) =20 =20 +class ObjectEntry(NamedTuple): + docname: str + node_id: str + objtype: str + aliased: bool + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -80,6 +89,7 @@ class QAPIModule(SphinxDirective): } =20 def run(self) -> List[Node]: + domain =3D cast(QAPIDomain, self.env.get_domain("qapi")) modname =3D self.arguments[0].strip() no_index =3D "no-index" in self.options or "noindex" in self.optio= ns =20 @@ -92,11 +102,14 @@ def run(self) -> List[Node]: inode =3D addnodes.index(entries=3D[]) =20 if not no_index: + # note module to the domain node_id =3D make_id(self.env, self.state.document, "module", m= odname) target =3D nodes.target("", "", ids=3D[node_id], ismod=3DTrue) self.set_source_info(target) self.state.document.note_explicit_target(target) =20 + domain.note_object(modname, "module", node_id, location=3Dtarg= et) + indextext =3D f"QAPI module; {modname}" inode =3D addnodes.index( entries=3D[ @@ -127,7 +140,12 @@ class QAPIDomain(Domain): name =3D "qapi" label =3D "QAPI" =20 - object_types: Dict[str, ObjType] =3D {} + # This table associates cross-reference object types (key) with an + # ObjType instance, which defines the valid cross-reference roles + # for each object type. + object_types: Dict[str, ObjType] =3D { + "module": ObjType(_("module"), "mod", "any"), + } =20 # Each of these provides a rST directive, # e.g. .. qapi:module:: block-core @@ -136,13 +154,70 @@ class QAPIDomain(Domain): } =20 roles =3D {} - initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D {} + + # Moved into the data property at runtime; + # this is the internal index of reference-able objects. + initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D { + "objects": {}, # fullname -> ObjectEntry + } + indices =3D [] =20 + @property + def objects(self) -> Dict[str, ObjectEntry]: + ret =3D self.data.setdefault("objects", {}) + return ret # type: ignore[no-any-return] + + def note_object( + self, + name: str, + objtype: str, + node_id: str, + aliased: bool =3D False, + location: Any =3D None, + ) -> None: + """Note a QAPI object for cross reference.""" + if name in self.objects: + other =3D self.objects[name] + if other.aliased and aliased is False: + # The original definition found. Override it! + pass + elif other.aliased is False and aliased: + # The original definition is already registered. + return + else: + # duplicated + logger.warning( + __( + "duplicate object description of %s, " + "other instance in %s, use :no-index: for one of t= hem" + ), + name, + other.docname, + location=3Dlocation, + ) + self.objects[name] =3D ObjectEntry( + self.env.docname, node_id, objtype, aliased + ) + + def clear_doc(self, docname: str) -> None: + for fullname, obj in list(self.objects.items()): + if obj.docname =3D=3D docname: + del self.objects[fullname] + def merge_domaindata( self, docnames: AbstractSet[str], otherdata: Dict[str, Any] ) -> None: - pass + for fullname, obj in otherdata["objects"].items(): + if obj.docname in docnames: + # Sphinx's own python domain doesn't appear to bother to + # check for collisions. Assert they don't happen and + # we'll fix it if/when the case arises. + assert fullname not in self.objects, ( + "bug - collision on merge?" + f" {fullname=3D} {obj=3D} {self.objects[fullname]=3D}" + ) + self.objects[fullname] =3D obj =20 def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any: # pylint: disable=3Dunused-argument --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146505; cv=none; d=zohomail.com; s=zohoarc; b=Zk/jtiJLcFRW+MdRiZYhpJ9aZnAhOYWr6LbvRK2m9+/vBL6jkP0QBoeyXJW/03H9R5gZR1q9ktVyEcj9tEDMoaTQROhaDi0B3Zms7W5pvTjdfLmnYl4ENXosoF/Q9FWnVAixBCBiCJTspSuhR4GuRAwLjIt7ktryhYZdQFrKy2A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146505; 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=eLKQxzj4s8eRpQziP7kQUeQMQDmRMosC+w0qxb65wKk=; b=JqyYUE/WK6VoISJtwGw00TVoTNrXSjEzmj5n1hHPFu86SKAygM/hj9Fq2c4KhCRi1hbmJIuAY3PT0jBHq+esksXsXpPkLxVqVGA5U4zdVnLutYDPEaxLdZi6hRm0XfphDj7Dhs5VAuK/FhNeA48ukZuGpleSfo7Z4NEHlXEPNfk= 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 17411465053180.7817650543455557; Tue, 4 Mar 2025 19:48:25 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfic-0005Pf-Rf; Tue, 04 Mar 2025 22:46:50 -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 1tpfiZ-0005Oa-7M for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:47 -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 1tpfiX-00062x-N6 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:46 -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-244-U1-V5-DPPwmFw10mDOjTsg-1; Tue, 04 Mar 2025 22:46:40 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 9D8DA1955BC9; Wed, 5 Mar 2025 03:46:39 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 306771956095; Wed, 5 Mar 2025 03:46:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146405; 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=eLKQxzj4s8eRpQziP7kQUeQMQDmRMosC+w0qxb65wKk=; b=FHIJzQr1LNWqECi6QwVlMAv9QdUrpy7bBXBRnr8q/H3eLIXU8qNeLzQiZV6n1toSCKumg0 vsXCfoMM2nUvJ0HebfOL81I+PVmYUmIndTXk+QOOqj97tF3cj9WWCu1CeWMbwfIhF2F4jG diWGY/+mDllRxgUiZ5Y8GFK729cvL1I= X-MC-Unique: U1-V5-DPPwmFw10mDOjTsg-1 X-Mimecast-MFC-AGG-ID: U1-V5-DPPwmFw10mDOjTsg_1741146399 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 07/57] docs/qapi-domain: add QAPI index Date: Tue, 4 Mar 2025 22:45:16 -0500 Message-ID: <20250305034610.960147-8-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146506821019100 Content-Type: text/plain; charset="utf-8" Use the QAPI object registry to generate a special index just for QAPI definitions. The index can show entries both by definition type and all together, alphabetically. The index can be linked from anywhere in the QEMU manual by using the reference `qapi-index`. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 76 +++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index b17fcb93f24..716a38a5f00 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -13,6 +13,7 @@ Iterable, List, NamedTuple, + Optional, Tuple, cast, ) @@ -22,7 +23,12 @@ =20 from compat import nested_parse from sphinx import addnodes -from sphinx.domains import Domain, ObjType +from sphinx.domains import ( + Domain, + Index, + IndexEntry, + ObjType, +) from sphinx.locale import _, __ from sphinx.util import logging from sphinx.util.docutils import SphinxDirective @@ -53,9 +59,10 @@ class QAPIModule(SphinxDirective): a pass-through for the content body. Named section titles are allowed in the content body. =20 - Use this directive to associate subsequent definitions with the - module they are defined in for purposes of search and QAPI index - organization. + Use this directive to create entries for the QAPI module in the + global index and the qapi index; as well as to associate subsequent + definitions with the module they are defined in for purposes of + search and QAPI index organization. =20 :arg: The name of the module. :opt no-index: Don't add cross-reference targets or index entries. @@ -134,6 +141,62 @@ def run(self) -> List[Node]: return ret =20 =20 +class QAPIIndex(Index): + """ + Index subclass to provide the QAPI definition index. + """ + + # pylint: disable=3Dtoo-few-public-methods + + name =3D "index" + localname =3D _("QAPI Index") + shortname =3D _("QAPI Index") + + def generate( + self, + docnames: Optional[Iterable[str]] =3D None, + ) -> Tuple[List[Tuple[str, List[IndexEntry]]], bool]: + assert isinstance(self.domain, QAPIDomain) + content: Dict[str, List[IndexEntry]] =3D {} + collapse =3D False + + # list of all object (name, ObjectEntry) pairs, sorted by name + # (ignoring the module) + objects =3D sorted( + self.domain.objects.items(), + key=3Dlambda x: x[0].split(".")[-1].lower(), + ) + + for objname, obj in objects: + if docnames and obj.docname not in docnames: + continue + + # Strip the module name out: + objname =3D objname.split(".")[-1] + + # Add an alphabetical entry: + entries =3D content.setdefault(objname[0].upper(), []) + entries.append( + IndexEntry( + objname, 0, obj.docname, obj.node_id, obj.objtype, "",= "" + ) + ) + + # Add a categorical entry: + category =3D obj.objtype.title() + "s" + entries =3D content.setdefault(category, []) + entries.append( + IndexEntry(objname, 0, obj.docname, obj.node_id, "", "", "= ") + ) + + # alphabetically sort categories; type names first, ABC entries la= st. + sorted_content =3D sorted( + content.items(), + key=3Dlambda x: (len(x[0]) =3D=3D 1, x[0]), + ) + return sorted_content, collapse + + class QAPIDomain(Domain): """QAPI language domain.""" =20 @@ -161,7 +224,10 @@ class QAPIDomain(Domain): "objects": {}, # fullname -> ObjectEntry } =20 - indices =3D [] + # Index pages to generate; each entry is an Index class. + indices =3D [ + QAPIIndex, + ] =20 @property def objects(self) -> Dict[str, ObjectEntry]: --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146516; cv=none; d=zohomail.com; s=zohoarc; b=ftuRXjo0HUAm5MUqEAJCOm8x+QWdvb9cItCuHKiirtlzABdaF+dh7qXZwro/Cefo9PrJoZ09tGvPxZmwzUuFfr+SI5/7as/8ZsSKvq/ZSbvLmwzhoz1KJlkoQaci0IcHq36kIKRmrSKpnBp/gc1xQ42x85Gy2SNo5LEkU6ugeBs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146516; 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=TxlPGnoKNgS3wVCveAZcb9oK5G1y9jJIDGz+TMmNLUQ=; b=lqHI2aAx3sv4MNnrgnkZsaGx1mS+OycSZBahCwi74PE9sF6cdNhxTmNfUGakHF1a4Ai4s1STlX5X+jsAK9QEwFiuQJO4MkWtEnOWmOkYfqRv807U89YAz1tGe1d/+laI6TZjiPaBBBCXlM+8yZe2Jzm3nZeEX/dNtViLAfaOtac= 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 17411465168671021.4840821180873; Tue, 4 Mar 2025 19:48:36 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfil-0005Ql-2q; Tue, 04 Mar 2025 22:46: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 1tpfik-0005QW-38 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46: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 1tpfih-00064B-Bq for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:46:57 -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-6-rOcaZGNcPSqQtfKHYeEhpA-1; Tue, 04 Mar 2025 22:46:44 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 DCDD61954234; Wed, 5 Mar 2025 03:46:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 046B81956095; Wed, 5 Mar 2025 03:46:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146412; 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=TxlPGnoKNgS3wVCveAZcb9oK5G1y9jJIDGz+TMmNLUQ=; b=eOSBlFz0cWWKhKWtlzIQGffj7LTV80FWdw98DcWtfpaKHNrqzdrkEMHXKAj8IQg5Ayna84 xUoNUJdQDqmt6QnPXjb98CNnyLTHLWwZk+Lrs6lGZX9J3YLThSR2AVC5j6VTCP9Flzgc/K Xtix+CvJ9EuJuoRAih0NbbBE9o3xcHc= X-MC-Unique: rOcaZGNcPSqQtfKHYeEhpA-1 X-Mimecast-MFC-AGG-ID: rOcaZGNcPSqQtfKHYeEhpA_1741146403 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 08/57] docs/qapi-domain: add resolve_any_xref() Date: Tue, 4 Mar 2025 22:45:17 -0500 Message-ID: <20250305034610.960147-9-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146517139019000 Content-Type: text/plain; charset="utf-8" Add the ability to resolve cross-references using the `any` cross-reference syntax. Adding QAPI-specific cross-reference roles will be added in a forthcoming commit, and will share the same find_obj() helper. (There's less code needed for the generic cross-reference resolver, so it comes first in this series.) Once again, this code is based very heavily on sphinx.domains.python. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 98 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 716a38a5f00..744956045e8 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -23,6 +23,7 @@ =20 from compat import nested_parse from sphinx import addnodes +from sphinx.addnodes import pending_xref from sphinx.domains import ( Domain, Index, @@ -32,13 +33,15 @@ from sphinx.locale import _, __ from sphinx.util import logging from sphinx.util.docutils import SphinxDirective -from sphinx.util.nodes import make_id +from sphinx.util.nodes import make_id, make_refnode =20 =20 if TYPE_CHECKING: from docutils.nodes import Element, Node =20 from sphinx.application import Sphinx + from sphinx.builders import Builder + from sphinx.environment import BuildEnvironment from sphinx.util.typing import OptionSpec =20 logger =3D logging.getLogger(__name__) @@ -285,9 +288,96 @@ def merge_domaindata( ) self.objects[fullname] =3D obj =20 - def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any: - # pylint: disable=3Dunused-argument - return [] + def find_obj( + self, modname: str, name: str, typ: Optional[str] + ) -> list[tuple[str, ObjectEntry]]: + """ + Find a QAPI object for "name", perhaps using the given module. + + Returns a list of (name, object entry) tuples. + + :param modname: The current module context (if any!) + under which we are searching. + :param name: The name of the x-ref to resolve; + may or may not include a leading module. + :param type: The role name of the x-ref we're resolving, if provid= ed. + (This is absent for "any" lookups.) + """ + if not name: + return [] + + names: list[str] =3D [] + matches: list[tuple[str, ObjectEntry]] =3D [] + + fullname =3D name + if "." in fullname: + # We're searching for a fully qualified reference; + # ignore the contextual module. + pass + elif modname: + # We're searching for something from somewhere; + # try searching the current module first. + # e.g. :qapi:cmd:`query-block` or `query-block` is being searc= hed. + fullname =3D f"{modname}.{name}" + + if typ is None: + # type isn't specified, this is a generic xref. + # search *all* qapi-specific object types. + objtypes: Optional[List[str]] =3D list(self.object_types) + else: + # type is specified and will be a role (e.g. obj, mod, cmd) + # convert this to eligible object types (e.g. command, module) + # using the QAPIDomain.object_types table. + objtypes =3D self.objtypes_for_role(typ) + + # Either we should have been given no type, or the type we were + # given should correspond to at least one real actual object + # type. + assert objtypes + + if name in self.objects and self.objects[name].objtype in objtypes: + names =3D [name] + elif ( + fullname in self.objects + and self.objects[fullname].objtype in objtypes + ): + names =3D [fullname] + else: + # exact match wasn't found; e.g. we are searching for + # `query-block` from a different (or no) module. + searchname =3D "." + name + names =3D [ + oname + for oname in self.objects + if oname.endswith(searchname) + and self.objects[oname].objtype in objtypes + ] + + matches =3D [(oname, self.objects[oname]) for oname in names] + if len(matches) > 1: + matches =3D [m for m in matches if not m[1].aliased] + return matches + + def resolve_any_xref( + self, + env: BuildEnvironment, + fromdocname: str, + builder: Builder, + target: str, + node: pending_xref, + contnode: Element, + ) -> List[Tuple[str, nodes.reference]]: + results: List[Tuple[str, nodes.reference]] =3D [] + matches =3D self.find_obj(node.get("qapi:module"), target, None) + for name, obj in matches: + rolename =3D self.role_for_objtype(obj.objtype) + assert rolename is not None + role =3D f"qapi:{rolename}" + refnode =3D make_refnode( + builder, fromdocname, obj.docname, obj.node_id, contnode, = name + ) + results.append((role, refnode)) + return results =20 =20 def setup(app: Sphinx) -> Dict[str, Any]: --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146590; cv=none; d=zohomail.com; s=zohoarc; b=Od7Cm7Sv3Rc8UG9LYszxpSfyK3lvcx2W7lZ/5CzdyHCTTudT1WvoMm2rrewkIwv9IIxnL4CZP0CtT0YB0VPJ0qRpC/6N1NOFSZibsV/vK0pwb7AYIYr//vlRf3U41TP7JpdZP53i+S46xlWMoh69S+efOLib3FrSDYUx4MY7Lto= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146590; 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=Qxd/WreSwxn5nYmmU7pAEQlWlhjR69Z++MyGnROnxpY=; b=Onve+QAEOIah/tcB1eLbU0hhQI86lKDr8+rbcsw0eBekY27UdeRial1ELQ0qJTSEZna1RSwi7+p1WaaEHsCYYEwvolr5nMk4Ba7TPW1xcQEprX3u8Sed7hSGlJrhD5m5VfQk5v0jFHO4Ko8fikBBjkdELcTcik5IUhATScqIh14= 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 1741146590008867.4097858800409; Tue, 4 Mar 2025 19:49:50 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfip-0005Rl-Ci; Tue, 04 Mar 2025 22:47:03 -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 1tpfio-0005Rb-2U for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:02 -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 1tpfim-00065A-BC for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:01 -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-522-QUiHEs68MpWBkWNnwbWHkg-1; Tue, 04 Mar 2025 22:46:48 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 56F02180025E; Wed, 5 Mar 2025 03:46:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 5219D1956095; Wed, 5 Mar 2025 03:46:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146419; 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=Qxd/WreSwxn5nYmmU7pAEQlWlhjR69Z++MyGnROnxpY=; b=cS9z0rsAndwxoM2u0URV//vGNnb7V4Rjugdc20fI6YP2qv6Ewwg/8SSiiDwJ3gP2peXEXY /MptL7voFL1uh3QvqgEUcHlG3Y1bwbdwvkH+WCxMVAbX9LzoW0JEZYIajmzgE8EMZL+hkc iza7QKC16SwOtDur6zyTWQyli+lneKE= X-MC-Unique: QUiHEs68MpWBkWNnwbWHkg-1 X-Mimecast-MFC-AGG-ID: QUiHEs68MpWBkWNnwbWHkg_1741146407 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 09/57] docs/qapi-domain: add QAPI xref roles Date: Tue, 4 Mar 2025 22:45:18 -0500 Message-ID: <20250305034610.960147-10-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146590906019100 Content-Type: text/plain; charset="utf-8" Add domain-specific cross-reference syntax. As of this commit, that means new :qapi:mod:`block-core` and :qapi:any:`block-core` referencing syntax. :mod: will only find modules, but :any: will find anything registered to the QAPI domain. (In forthcoming commits, this means commands, events, enums, etc.) Creating the cross-references is powered by the QAPIXRefRole class; resolving them is handled by QAPIDomain.resolve_xref(). QAPIXrefRole is copied almost verbatim from Sphinx's own PyXrefRole. PyXrefRole (and QAPIXrefRole) adds two features over the base class: (1) Creating a cross-reference with e.g. :py:class:`~class.name` instructs sphinx to omit the fully qualified parts of the resolved name from the actual link text. This may be useful in the future if we add namespaces to QAPI documentation, e.g. :qapi:cmd:`~qsd.blockdev-backup` could link to the QSD-specific documentation for blockdev-backup while omitting that prefix from the link text. (2) Prefixing the link target with a "." changes the search behavior to prefer locally-scoped items first. I think both of these are worth keeping to help manage future namespace issues between QEMU, QSD and QGA; but it's possible it's extraneous. It may possibly be worth keeping just to keep feature parity with Sphinx's other domains; e.g. "principle of least surprise". Dunno. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 88 +++++++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 744956045e8..104bae709f3 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -31,6 +31,7 @@ ObjType, ) from sphinx.locale import _, __ +from sphinx.roles import XRefRole from sphinx.util import logging from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode @@ -54,6 +55,54 @@ class ObjectEntry(NamedTuple): aliased: bool =20 =20 +class QAPIXRefRole(XRefRole): + + def process_link( + self, + env: BuildEnvironment, + refnode: Element, + has_explicit_title: bool, + title: str, + target: str, + ) -> tuple[str, str]: + refnode["qapi:module"] =3D env.ref_context.get("qapi:module") + + # Cross-references that begin with a tilde adjust the title to + # only show the reference without a leading module, even if one + # was provided. This is a Sphinx-standard syntax; give it + # priority over QAPI-specific type markup below. + hide_module =3D False + if target.startswith("~"): + hide_module =3D True + target =3D target[1:] + + # Type names that end with "?" are considered optional + # arguments and should be documented as such, but it's not + # part of the xref itself. + if target.endswith("?"): + refnode["qapi:optional"] =3D True + target =3D target[:-1] + + # Type names wrapped in brackets denote lists. strip the + # brackets and remember to add them back later. + if target.startswith("[") and target.endswith("]"): + refnode["qapi:array"] =3D True + target =3D target[1:-1] + + if has_explicit_title: + # Don't mess with the title at all if it was explicitly set. + # Explicit title syntax for references is e.g. + # :qapi:type:`target ` + # and this explicit title overrides everything else here. + return title, target + + title =3D target + if hide_module: + title =3D target.split(".")[-1] + + return title, target + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -219,7 +268,13 @@ class QAPIDomain(Domain): "module": QAPIModule, } =20 - roles =3D {} + # These are all cross-reference roles; e.g. + # :qapi:cmd:`query-block`. The keys correlate to the names used in + # the object_types table values above. + roles =3D { + "mod": QAPIXRefRole(), + "any": QAPIXRefRole(), # reference *any* type of QAPI object. + } =20 # Moved into the data property at runtime; # this is the internal index of reference-able objects. @@ -358,6 +413,37 @@ def find_obj( matches =3D [m for m in matches if not m[1].aliased] return matches =20 + def resolve_xref( + self, + env: BuildEnvironment, + fromdocname: str, + builder: Builder, + typ: str, + target: str, + node: pending_xref, + contnode: Element, + ) -> nodes.reference | None: + modname =3D node.get("qapi:module") + matches =3D self.find_obj(modname, target, typ) + + if not matches: + return None + + if len(matches) > 1: + logger.warning( + __("more than one target found for cross-reference %r: %s"= ), + target, + ", ".join(match[0] for match in matches), + type=3D"ref", + subtype=3D"qapi", + location=3Dnode, + ) + + name, obj =3D matches[0] + return make_refnode( + builder, fromdocname, obj.docname, obj.node_id, contnode, name + ) + def resolve_any_xref( self, env: BuildEnvironment, --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146516; cv=none; d=zohomail.com; s=zohoarc; b=bYxmw/CUdXF0xX+u1lT0Egtg3zOm5hKBPRdA4RnIusg9amWhBosNSSX7cITcbHFuN7vUUC7dh4gFCKQrLhzH+F6j2cqnOl5OsdRmV1yv8XlwE/2dW5mXIKezofT06tUgDx+uwwreULKKERkQzS53QKvqMd0xAKhOIFp8T/rQ9E8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146516; 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=4djS5SV15KM2T+0Lk2hLqTTPqnHTrvBn8oVnGScX2+0=; b=dg9sdpc55NvEtH0CFbSkh+hwYIJpMx9MjPDeECCclrNqZxE0a7hb8Ug8IeO/F4SXvMPJwyOlKcKyCF3NFhHHl3lScVbnm7whmgFq+yvrSExChJHkYXLiJlLlZqBG01684+0BoilVDKdx2DOZgX7CsMgFSV3/1El8eiFGcgDa4oA= 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 1741146516860134.39225894226377; Tue, 4 Mar 2025 19:48:36 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfiu-0005St-Pr; Tue, 04 Mar 2025 22:47:09 -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 1tpfis-0005Sh-TS for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:06 -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 1tpfir-000663-Hu for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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-421-jpPKxlJNOXGwQ4xSbAqtEg-1; Tue, 04 Mar 2025 22:46:51 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 69FCD18001CE; Wed, 5 Mar 2025 03:46:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E79041955DDD; Wed, 5 Mar 2025 03:46:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146424; 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=4djS5SV15KM2T+0Lk2hLqTTPqnHTrvBn8oVnGScX2+0=; b=LsNFs0u3OmHXWlcrJQL2NRRGqmbIzqS0IjFCdzlAq4AUqGNHPaMl4ASQzqpVayRYw1XARa CyYvluopFxzxWRlh46e6TI9apKoXxYbJtuNdknxqB6a6GtcYyGMxSAzpc3doWUKTG02D0p ir+lellyjzzZc8ZC2Dcd8VQmrIWaXJ0= X-MC-Unique: jpPKxlJNOXGwQ4xSbAqtEg-1 X-Mimecast-MFC-AGG-ID: jpPKxlJNOXGwQ4xSbAqtEg_1741146410 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 10/57] docs/qapi-domain: add compatibility node classes Date: Tue, 4 Mar 2025 22:45:19 -0500 Message-ID: <20250305034610.960147-11-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146518636019100 Content-Type: text/plain; charset="utf-8" Sphinx prior to v4.0 uses different classes for rendering elements of documentation objects; add some compatibility classes to use the right node classes conditionally. Signed-off-by: John Snow --- docs/sphinx/compat.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py index 792aca10e39..1f9f1f42ef7 100644 --- a/docs/sphinx/compat.py +++ b/docs/sphinx/compat.py @@ -2,12 +2,27 @@ Sphinx cross-version compatibility goop """ =20 -from docutils.nodes import Element +from typing import Callable =20 +from docutils.nodes import Element, Node, Text + +import sphinx +from sphinx import addnodes from sphinx.util.docutils import SphinxDirective, switch_source_input from sphinx.util.nodes import nested_parse_with_titles =20 =20 +SpaceNode: Callable[[str], Node] +KeywordNode: Callable[[str, str], Node] + +if sphinx.version_info[:3] >=3D (4, 0, 0): + SpaceNode =3D addnodes.desc_sig_space + KeywordNode =3D addnodes.desc_sig_keyword +else: + SpaceNode =3D Text + KeywordNode =3D addnodes.desc_annotation + + def nested_parse(directive: SphinxDirective, content_node: Element) -> Non= e: """ This helper preserves error parsing context across sphinx versions. --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146596; cv=none; d=zohomail.com; s=zohoarc; b=UMKTdYaHAK4K2EOWeWYxWgNYhAWhypmp+JyEwVJb7lGmsxJj0zLqSV4bOBYKNgLUbZ73oFWpRI9cyOAzd1Y/U/K/QVqB0Hm0QsjOIRb5+hZGXH4wsslg/OZbddDqCQwzAQgCzEeGpvBewJQe/+Ziq9DJxIelxdfFM3nAk+KPvig= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146596; 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=DyjACrY0my7wCr/yL1onWCjkED4tWYNrUnfInrUzYqo=; b=QtLDslzhdCFHxDJ9y386464/YEux0cKZzFVGE9vMlZESpypP3FBDQsjql1dpXfW1G4w67/CZ6OtMX/FwAprkKqUDJDQYlwb7f9x+T2HMyaSki09H1tY23moiju3QirOKc6rnXuy/LFpWmz+eSbM7pngR6TW0noSJ8HBaeEcb5SY= 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 1741146596114839.0786136302803; Tue, 4 Mar 2025 19:49:56 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfir-0005SR-20; Tue, 04 Mar 2025 22:47: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 1tpfip-0005Rm-El for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:03 -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 1tpfin-00065F-Je for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:03 -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-511-l2RzfjO1PwC42XOWigfVRg-1; Tue, 04 Mar 2025 22:46:56 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 0D6BD1800258; Wed, 5 Mar 2025 03:46:55 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 040D61956095; Wed, 5 Mar 2025 03:46:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146420; 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=DyjACrY0my7wCr/yL1onWCjkED4tWYNrUnfInrUzYqo=; b=gh4u+UpCA60UIto65Kxqxj4D1v5c1vpx01wAfGGmdGSqDba3nm9r7FwEP/ggaqf9UbA8g/ I8pisYCHXhBlXlSXgUd+byAh51DBHw2spLe3jX9LDRgpTZWrSRvhuCAHiIA1e3F8Yu6ndn 8aofSx36edKGygiiw65GJRobglMGWWs= X-MC-Unique: l2RzfjO1PwC42XOWigfVRg-1 X-Mimecast-MFC-AGG-ID: l2RzfjO1PwC42XOWigfVRg_1741146415 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 11/57] docs/qapi-domain: add qapi:command directive Date: Tue, 4 Mar 2025 22:45:20 -0500 Message-ID: <20250305034610.960147-12-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146597512019000 Content-Type: text/plain; charset="utf-8" This commit adds a stubbed version of QAPICommand that utilizes the QAPIObject class, the qapi:command directive, the :qapi:cmd: cross-reference role, and the "command" object type in the QAPI object registry. This commit also adds the aforementioned generic QAPIObject class for use in documenting various QAPI entities in the Sphinx ecosystem. They don't do anything *particularly* interesting yet, but that will come in forthcoming commits. Note: some versions of mypy get a little confused over the difference between class and instance variables; because sphinx's ObjectDescription does not declare option_spec as a ClassVar (even though it's obvious that it is), mypy may produce this error: qapi-domain.py:125: error: Cannot override instance variable (previously declared on base class "ObjectDescription") with class variable [misc] I can't control that; so silence the error with a pragma. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 146 ++++++++++++++++++++++++++++++++++++- 1 file changed, 144 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 104bae709f3..6168c23936f 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -21,9 +21,10 @@ from docutils import nodes from docutils.parsers.rst import directives =20 -from compat import nested_parse +from compat import KeywordNode, SpaceNode, nested_parse from sphinx import addnodes -from sphinx.addnodes import pending_xref +from sphinx.addnodes import desc_signature, pending_xref +from sphinx.directives import ObjectDescription from sphinx.domains import ( Domain, Index, @@ -103,6 +104,144 @@ def process_link( return title, target =20 =20 +# Alias for the return of handle_signature(), which is used in several pla= ces. +# (In the Python domain, this is Tuple[str, str] instead.) +Signature =3D str + + +class QAPIObject(ObjectDescription[Signature]): + """ + Description of a generic QAPI object. + + It's not used directly, but is instead subclassed by specific directiv= es. + """ + + # Inherit some standard options from Sphinx's ObjectDescription + option_spec: OptionSpec =3D ( # type:ignore[misc] + ObjectDescription.option_spec.copy() + ) + option_spec.update( + { + # Borrowed from the Python domain: + "module": directives.unchanged, # Override contextual module = name + } + ) + + def get_signature_prefix(self) -> List[nodes.Node]: + """Returns a prefix to put before the object name in the signature= .""" + assert self.objtype + return [ + KeywordNode("", self.objtype.title()), + SpaceNode(" "), + ] + + def get_signature_suffix(self) -> list[nodes.Node]: + """Returns a suffix to put after the object name in the signature.= """ + return [] + + def handle_signature(self, sig: str, signode: desc_signature) -> Signa= ture: + """ + Transform a QAPI definition name into RST nodes. + + This method was originally intended for handling function + signatures. In the QAPI domain, however, we only pass the + definition name as the directive argument and handle everything + else in the content body with field lists. + + As such, the only argument here is "sig", which is just the QAPI + definition name. + """ + modname =3D self.options.get( + "module", self.env.ref_context.get("qapi:module") + ) + + signode["fullname"] =3D sig + signode["module"] =3D modname + sig_prefix =3D self.get_signature_prefix() + if sig_prefix: + signode +=3D addnodes.desc_annotation( + str(sig_prefix), "", *sig_prefix + ) + signode +=3D addnodes.desc_name(sig, sig) + signode +=3D self.get_signature_suffix() + + return sig + + def _object_hierarchy_parts( + self, sig_node: desc_signature + ) -> Tuple[str, ...]: + if "fullname" not in sig_node: + return () + modname =3D sig_node.get("module") + fullname =3D sig_node["fullname"] + + if modname: + return (modname, *fullname.split(".")) + + return tuple(fullname.split(".")) + + def get_index_text(self, modname: str, name: Signature) -> str: + """Return the text for the index entry of the object.""" + # We don't care about the module name here: + # pylint: disable=3Dunused-argument + + # NB: this is used for the global index, not the QAPI index. + return f"{name} (QMP {self.objtype})" + + def add_target_and_index( + self, name: Signature, sig: str, signode: desc_signature + ) -> None: + # Called by ObjectDescription.run with the result of + # handle_signature; name is the return value of handle_signature + # where sig is the original argument to handle_signature. In our + # case, they're the same for now. + assert self.objtype + + modname =3D self.options.get( + "module", self.env.ref_context.get("qapi:module") + ) + # Here, sphinx decides to prepend the module name. OK. + fullname =3D (modname + "." if modname else "") + name + node_id =3D make_id(self.env, self.state.document, "", fullname) + signode["ids"].append(node_id) + self.state.document.note_explicit_target(signode) + + domain =3D cast(QAPIDomain, self.env.get_domain("qapi")) + domain.note_object(fullname, self.objtype, node_id, location=3Dsig= node) + + if "no-index-entry" not in self.options: + indextext =3D self.get_index_text(modname, name) + assert self.indexnode is not None + if indextext: + self.indexnode["entries"].append( + ("single", indextext, node_id, "", None) + ) + + def _toc_entry_name(self, sig_node: desc_signature) -> str: + # This controls the name in the TOC and on the sidebar. + + # This is the return type of _object_hierarchy_parts(). + toc_parts =3D cast(Tuple[str, ...], sig_node.get("_toc_parts", ())) + if not toc_parts: + return "" + + config =3D self.env.app.config + *parents, name =3D toc_parts + if config.toc_object_entries_show_parents =3D=3D "domain": + return sig_node.get("fullname", name) + if config.toc_object_entries_show_parents =3D=3D "hide": + return name + if config.toc_object_entries_show_parents =3D=3D "all": + return ".".join(parents + [name]) + return "" + + +class QAPICommand(QAPIObject): + """Description of a QAPI Command.""" + + # Nothing unique for now! Changed in later commits O:-) + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -260,12 +399,14 @@ class QAPIDomain(Domain): # for each object type. object_types: Dict[str, ObjType] =3D { "module": ObjType(_("module"), "mod", "any"), + "command": ObjType(_("command"), "cmd", "any"), } =20 # Each of these provides a rST directive, # e.g. .. qapi:module:: block-core directives =3D { "module": QAPIModule, + "command": QAPICommand, } =20 # These are all cross-reference roles; e.g. @@ -273,6 +414,7 @@ class QAPIDomain(Domain): # the object_types table values above. roles =3D { "mod": QAPIXRefRole(), + "cmd": QAPIXRefRole(), "any": QAPIXRefRole(), # reference *any* type of QAPI object. } =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146549; cv=none; d=zohomail.com; s=zohoarc; b=RgAq6IsyzsqpifpnbtbmtiRktRYWWFcq4/J/Bzhpot1X46B2scNnHE5sVxrypjiirKR7G4A1ya8bSpc24SCzz/jsYOiBbbPLdR78d2AYu4vnJ0b2qLrr8aPq8xnid8r2um0LDx0tunV3VxLBfoZpl/Vmyoetk+c9OTK0ljlMjbM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146549; 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=/RxCjFYPvrEydD2D4WJ3pep23Kg6DeegEtOUm7zlMIk=; b=IuAo4sDgCJzU3hhlDrhSeQP56g/o6I0NW9iWhakLCNSXTrZ3Z6GCvKLmQWeG5UU8/wfST8YDEDAQHJy1Rgl/AmDSFAIDkIvp4nTV01D5CBtwAaohL/a96ASdq8lVKEQBlAuvI3iPTAG7vto86Iya8wL28fP9yajCr+b9Xd1JagI= 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 1741146549818275.5313240200413; Tue, 4 Mar 2025 19:49:09 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk2-00014G-RY; Tue, 04 Mar 2025 22:48:18 -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 1tpfjz-0000oL-2z for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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 1tpfjx-0006Fp-7h for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:14 -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-84-PtLRJPgENVC4lt3XQHCfIw-1; Tue, 04 Mar 2025 22:47:01 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 586AE1955BFC; Wed, 5 Mar 2025 03:47:00 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E37501956095; Wed, 5 Mar 2025 03:46:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146492; 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=/RxCjFYPvrEydD2D4WJ3pep23Kg6DeegEtOUm7zlMIk=; b=B356igV3tXqBob/AsDqqPZVjtzR4DnHpua54pdgiWMPQEcfR86ITnSAgKhLhcpSLv4n5jF ZCLrfn2m8ENlVUOPz1O9Ov2AJ6fQvAI7SvzeF6TkgtYAxZ5YesOQ19wgywpSH3MMtIpymp Pl+XfeIM7VOT8CwzxyIM1UxEINtQ8jE= X-MC-Unique: PtLRJPgENVC4lt3XQHCfIw-1 X-Mimecast-MFC-AGG-ID: PtLRJPgENVC4lt3XQHCfIw_1741146420 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 12/57] docs/qapi-domain: add :since: directive option Date: Tue, 4 Mar 2025 22:45:21 -0500 Message-ID: <20250305034610.960147-13-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146551223019000 Content-Type: text/plain; charset="utf-8" Add a little special markup for registering "Since:" information. Adding it as an option instead of generic content lets us hoist the information into the Signature bar, optionally put it in the index, etc. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 6168c23936f..9919dacd4e6 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -4,6 +4,7 @@ =20 from __future__ import annotations =20 +import re from typing import ( TYPE_CHECKING, AbstractSet, @@ -104,6 +105,18 @@ def process_link( return title, target =20 =20 +def since_validator(param: str) -> str: + """ + Validate the `:since: X.Y` option field. + """ + match =3D re.match(r"[0-9]+\.[0-9]+", param) + if not match: + raise ValueError( + f":since: requires a version number in X.Y format; not {param!= r}" + ) + return param + + # Alias for the return of handle_signature(), which is used in several pla= ces. # (In the Python domain, this is Tuple[str, str] instead.) Signature =3D str @@ -124,6 +137,8 @@ class QAPIObject(ObjectDescription[Signature]): { # Borrowed from the Python domain: "module": directives.unchanged, # Override contextual module = name + # These are QAPI originals: + "since": since_validator, } ) =20 @@ -135,9 +150,19 @@ def get_signature_prefix(self) -> List[nodes.Node]: SpaceNode(" "), ] =20 - def get_signature_suffix(self) -> list[nodes.Node]: + def get_signature_suffix(self) -> List[nodes.Node]: """Returns a suffix to put after the object name in the signature.= """ - return [] + ret: List[nodes.Node] =3D [] + + if "since" in self.options: + ret +=3D [ + SpaceNode(" "), + addnodes.desc_sig_element( + "", f"(Since: {self.options['since']})" + ), + ] + + return ret =20 def handle_signature(self, sig: str, signode: desc_signature) -> Signa= ture: """ --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146834; cv=none; d=zohomail.com; s=zohoarc; b=D56eRsLuAznYK3RxrG6agI7zm60Wk0BBu7aUFv5kbomtD6GzhCPy88ZERl+0XmZEwJfxnq1ZOnneOIGGamMxw8NN0soX2505Watld9sp/+n0BfkQO1X2l823wiAnuNMJb/ipaPrVNoPWGipHX1A1dY1W7ago7A7CuwcPtj6wZU0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146834; 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=78hYwqMTngVHkVcnOaWTLp8eTkO0LIj42mpYOykYBAY=; b=DQ7F3g5KebU+fHCB+QpJX0pbgGRdqdJtoQWCLCl/gYIBj7ZeB4uXkYmGki2RBit9XuhDoaGtRXdP1FJdLEE+Ca+XdW3pzTLAJTCN8OmbJcOKI5SgOLaTadrY3ZROhodTamc/Bass8Ih/P1F6YheG38Afr1keA8yYhNVy0AnU7Vo= 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 1741146834941258.0627019661043; Tue, 4 Mar 2025 19:53:54 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfj7-0005qM-Bg; Tue, 04 Mar 2025 22:47: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 1tpfj4-0005jB-Ln for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:18 -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 1tpfiy-00066s-R2 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:18 -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-515-cbarEL_tMBKKEFsVpZhHqw-1; Tue, 04 Mar 2025 22:47:04 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 070A91801A0A; Wed, 5 Mar 2025 03:47:03 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3A9A51955DDD; Wed, 5 Mar 2025 03:47:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146432; 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=78hYwqMTngVHkVcnOaWTLp8eTkO0LIj42mpYOykYBAY=; b=SC7G4ghPc/MylMkGuiUaPnaEJSbsTcOwV5NThY/yQ/EX4+rt6umEZF8EqQXPUONEhdkl+c NOn40TfPXU7DY6Owfz2LfPGqMLIAmTnXQg8isZTnOVt7NMPJVVO1GKEQzdXDYVJeGV+qQK aQ3mwNeTNVtgyVVuVAGtsdeSULtNz5I= X-MC-Unique: cbarEL_tMBKKEFsVpZhHqw-1 X-Mimecast-MFC-AGG-ID: cbarEL_tMBKKEFsVpZhHqw_1741146423 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 13/57] docs/qapi-domain: add "Arguments:" field lists Date: Tue, 4 Mar 2025 22:45:22 -0500 Message-ID: <20250305034610.960147-14-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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_PASS=-0.001, T_SPF_HELO_TEMPERROR=0.01 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: 1741146835521019100 Content-Type: text/plain; charset="utf-8" This adds special rendering for Sphinx's typed field lists. This patch does not add any QAPI-aware markup, rendering, or cross-referencing for the type names, yet. That feature requires a subclass to TypedField which will happen in its own commit quite a bit later in this series; after all the basic fields and objects have been established first. The syntax for this field is: :arg type name: description description cont'd You can omit the type or the description, but you cannot omit the name -- if you do so, it degenerates into a "normal field list" entry, and probably isn't what you want. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 9919dacd4e6..64b540ff940 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -35,6 +35,7 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging +from sphinx.util.docfields import TypedField from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode =20 @@ -264,7 +265,18 @@ def _toc_entry_name(self, sig_node: desc_signature) ->= str: class QAPICommand(QAPIObject): """Description of a QAPI Command.""" =20 - # Nothing unique for now! Changed in later commits O:-) + doc_field_types =3D QAPIObject.doc_field_types.copy() + doc_field_types.extend( + [ + # :arg TypeName ArgName: descr + TypedField( + "argument", + label=3D_("Arguments"), + names=3D("arg",), + can_collapse=3DFalse, + ), + ] + ) =20 =20 class QAPIModule(SphinxDirective): --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146453; cv=none; d=zohomail.com; s=zohoarc; b=SkyDCeQjBxfpT/MO1plyC/7PpyPg0w9c8X7Ljigw7hqZdD5fxLHNk2mFiR6od6XvVcQl9sILclFJPgnYgNypUIf6OP+ora0Q3jH6d1AzFBYVV0JAUJgd/gz31O0Y0tTLgXd7j9lHLtLfyQ8DjmhjY07Ww3fKyEQIMqBpxATbgrE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146453; 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=I5dQJVpp3RgPXRLeBr3NVPTTTQxINzVma2R8xpIHoNs=; b=BzUXYlmsUcSuHv+1HGkdoUmhQzsKhghC/hilRIl5ncnpyMo16tHRAACd4422L7VOMl7eFiirjC2Ue1w/DugY0t0yKrPtyjV+n7uKcclSPXQqZwG4cjio6d/IsWJUAnhUtS/6Jn86sYeqXNqKT4cf2ISDO4d2HDBpU8xbQNJYzlg= 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 1741146453131171.52694018974887; Tue, 4 Mar 2025 19:47:33 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfj4-0005is-PM; Tue, 04 Mar 2025 22:47:18 -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 1tpfj0-0005bh-EW for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:15 -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 1tpfix-00066i-MQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:13 -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-471---wOhkQbNCWNAjxo-0opog-1; Tue, 04 Mar 2025 22:47:08 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 AE7B81954199; Wed, 5 Mar 2025 03:47:06 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 72E6C1956095; Wed, 5 Mar 2025 03:47:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146430; 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=I5dQJVpp3RgPXRLeBr3NVPTTTQxINzVma2R8xpIHoNs=; b=bUWoHo5RUb2r+AyzwIgV8yDTLjsAPPUU58BiJT0aAeasJlMWwxBQYiZjK1xfFRLxfGD7BW r5x5kZ+0Vm/Ek6OHptzzThFLvNic2BBBmMvz1i88JY4LEYiH/AAzE20N/jVkJa8Ewl1IZR +9wu+InOB8R3dppUJRT8+Y7+kT3Jux4= X-MC-Unique: --wOhkQbNCWNAjxo-0opog-1 X-Mimecast-MFC-AGG-ID: --wOhkQbNCWNAjxo-0opog_1741146427 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 14/57] docs/qapi-domain: add "Features:" field lists Date: Tue, 4 Mar 2025 22:45:23 -0500 Message-ID: <20250305034610.960147-15-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146454957019000 Content-Type: text/plain; charset="utf-8" Add support for Features field lists. There is no QAPI-specific functionality here, but this could be changed if desired (if we wanted the feature names to link somewhere, for instance.) This feature list doesn't have any restrictions, so it can be used to document object-wide features or per-member features as deemed appropriate. It's essentially free-form text. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 64b540ff940..e1b766d9481 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -35,7 +35,7 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging -from sphinx.util.docfields import TypedField +from sphinx.util.docfields import GroupedField, TypedField from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode =20 @@ -143,6 +143,16 @@ class QAPIObject(ObjectDescription[Signature]): } ) =20 + doc_field_types =3D [ + # :feat name: descr + GroupedField( + "feature", + label=3D_("Features"), + names=3D("feat",), + can_collapse=3DFalse, + ), + ] + def get_signature_prefix(self) -> List[nodes.Node]: """Returns a prefix to put before the object name in the signature= .""" assert self.objtype --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146492; cv=none; d=zohomail.com; s=zohoarc; b=PIv+61AzkYsOFYFlIL55oLcir8LIgEItH4MX1F9M8XhxZW9hjkYfQDRiG7p7ORCl/iblnnVCET2v584sPanV7iPcY93WC0bKR9mk6+jzdb5tyXU8qMmmjkak7uApIcWuLdoY6HtkLmEU+6MhTM+bogc2v0mddL1WFVOTweTGT/Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146492; 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=av/LEwhuXaKikBGm7XHenppYaeUIC4NUezABwrF9viY=; b=RD+VRtf4RjV8wB7IbjiFDK8qAXgNddewWEMhELT/9nkeFIO8DGhkNRfqKzP/ri0+ai2hus3OtfnBfF83TWZB8s8MIRZUZ8/RbgiB9bUMP3lAjKF0KncNWoO0Ff/0Y1fiaAuhkLqU1fK/r/nFNfHh8AlDx3+7DBu1SkO7TJsxfXs= 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 1741146492943379.29889406827874; Tue, 4 Mar 2025 19:48:12 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfj9-0005u4-1j; Tue, 04 Mar 2025 22:47: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 1tpfj4-0005iG-Hs for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:18 -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 1tpfj1-00067O-C7 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:17 -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-596-mMwqJkyBOnmfS4B7d3yLQA-1; Tue, 04 Mar 2025 22:47:11 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 9367F180AF51; Wed, 5 Mar 2025 03:47:10 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 277221955DDD; Wed, 5 Mar 2025 03:47:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146434; 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=av/LEwhuXaKikBGm7XHenppYaeUIC4NUezABwrF9viY=; b=F1rAz1JbWFlM/VNucPD++9NkHhhZK6I7QqB/QwMhAkLGk099vgTcGcAKPA2c1cO1Mg+jRn NyMyRHN7UtYa2tLbYPtpvk80kuGUOcKIBGZX2/hgC/RtIQ/fgoqS5/9SRBLYtITLJgUwVT qFegNo5svpL/RKka3Z11+94TSf8vnCI= X-MC-Unique: mMwqJkyBOnmfS4B7d3yLQA-1 X-Mimecast-MFC-AGG-ID: mMwqJkyBOnmfS4B7d3yLQA_1741146430 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 15/57] docs/qapi-domain: add "Errors:" field lists Date: Tue, 4 Mar 2025 22:45:24 -0500 Message-ID: <20250305034610.960147-16-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146495004019000 Content-Type: text/plain; charset="utf-8" ``:error: descr`` can now be used to document error conditions. The format of the description is not defined here; so the ability to name specific types is left to the document writer. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index e1b766d9481..d60cccb8e95 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -35,7 +35,7 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging -from sphinx.util.docfields import GroupedField, TypedField +from sphinx.util.docfields import Field, GroupedField, TypedField from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode =20 @@ -285,6 +285,13 @@ class QAPICommand(QAPIObject): names=3D("arg",), can_collapse=3DFalse, ), + # :error: descr + Field( + "error", + label=3D_("Errors"), + names=3D("error", "errors"), + has_arg=3DFalse, + ), ] ) =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146850; cv=none; d=zohomail.com; s=zohoarc; b=LEpTP9PYlpiXpFYBVCnc3++FPdvGbPeC9MJ4lIqiSEydfa/19ex6+JAkGnlhYuVWIHV/xRCWit5idf2Ds912a3QJGEB8QtBX4YWRjh1B0w/gmGQa0PAPalj8KY99d9VyeyojFNA0l/U5BQjubeIlEFRQIl9WFRMjVt5MjvC2d4M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146850; 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=HLEE6Amwl+9tfhKr+WfSmS1kiZKCPAngGeUn8RMXjNk=; b=HEvb0d+OyqJm/IXuXS+Ox/Qly8oX7tMzcSL/Fp7SGRh6w/TwszshKk718Pf9shF+TqANtOZDMSCUpDe/vAmwAbCK49uiO0MffUuOMDYIgtHKDe//yU/UTWWb6Kr0wHDw01r3IeH7fRG9kKhgW2m0oMnRQ02/9fFgU2lHQlKTsAs= 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 1741146850061399.78497014177356; Tue, 4 Mar 2025 19:54:10 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjA-0005vp-Cy; Tue, 04 Mar 2025 22:47: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 1tpfj7-0005q7-0W for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:21 -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 1tpfj5-00068C-8X for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:20 -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-607-386jWLClNfaDo6EaPENiow-1; Tue, 04 Mar 2025 22:47:15 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 5EE7C18001C8; Wed, 5 Mar 2025 03:47:14 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3FF991956095; Wed, 5 Mar 2025 03:47:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146438; 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=HLEE6Amwl+9tfhKr+WfSmS1kiZKCPAngGeUn8RMXjNk=; b=VkBYaci2PlA2b5DISq8sdTp472wUERXO+q34jTcebPOO4Jt7mo7D7Il0PTB5BOaegocSE9 CUKzPliccJBjEZIlFqXSqM2CzzcJ+MHBMxaDnU0PSUdBDkRXS5WtD7TBCQBU8wtvrV7IcZ hwnvhb0AQwlb4myyUAutUwjN/1g1Oho= X-MC-Unique: 386jWLClNfaDo6EaPENiow-1 X-Mimecast-MFC-AGG-ID: 386jWLClNfaDo6EaPENiow_1741146434 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 16/57] docs/qapi-domain: add "Returns:" field lists Date: Tue, 4 Mar 2025 22:45:25 -0500 Message-ID: <20250305034610.960147-17-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146851549019100 Content-Type: text/plain; charset="utf-8" Add "Returns:" field list syntax to QAPI Commands. Like "Arguments:" and "Errors:", the type name isn't currently processed for cross-referencing, but this will be addressed in a forthcoming commit. This patch adds "errors" as a GroupedField, which means that multiple return values can be annotated - this is only done because Sphinx does not seemingly (Maybe I missed it?) support mandatory type arguments to Ungrouped fields. Because we want to cross-reference this type information later, we want to make the type argument mandatory. As a result, you can technically add multiple :return: fields, though I'm not aware of any circumstance in which you'd need or want to. Recommendation: "Don't do that, then." Since this field describes an action/event instead of describing a list of nouns (arguments, features, errors), I added both the imperative and indicative forms (:return: and :returns:) to allow doc writers to use whichever mood "feels right" in the source document. The rendered output will always use the "Returns:" label, however. I'm sure you'll let me know how you feel about that. O:-) Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d60cccb8e95..7531bdfbba7 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -292,6 +292,13 @@ class QAPICommand(QAPIObject): names=3D("error", "errors"), has_arg=3DFalse, ), + # :returns TypeName: descr + GroupedField( + "returnvalue", + label=3D_("Returns"), + names=3D("return", "returns"), + can_collapse=3DTrue, + ), ] ) =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146472; cv=none; d=zohomail.com; s=zohoarc; b=oEVpnJbXPAVRZz2uRtzwiIE2kr1oTKd85RUTfUnVbhJGlLgRc1DNoWtUVFWefSFaVoPS/L6qAvv1i44OZBROJ+NRdN+lv05epROxG6sOXJopDls9792kDr0x/Cf4UYPr4auNQYrhKE5S3phAI91idv0dDGo5Fv9Jva++Wo5Smpg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146472; 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=MDXyivQbbnao2sqE7jinSEqJyRZAWAJfzIaOFfRSk2o=; b=JpjUepKkAM6XXfQcXwV6Cb8UKnYSqv0+/dPY9sOnBNioqdy/TGVUndOQxhtS9YUatbw7aGOsKvD7jpV6hSg3GGgqJczSaEK4AD6XwUn/foLO8IMQBeoxtm3xvSWQZG7LxP6RqdVlgFk+Z6uAkyAm7AjqDhxMdAVDiJS+OsJeDkQ= 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 1741146472565957.5430301162074; Tue, 4 Mar 2025 19:47:52 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjE-0005yH-62; Tue, 04 Mar 2025 22:47: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 1tpfjA-0005wW-St for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:25 -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 1tpfj9-00068l-Fg for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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-654-ZhXVrGepMXSVBjtoXAzl1g-1; Tue, 04 Mar 2025 22:47:19 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 5DDF51954B19; Wed, 5 Mar 2025 03:47:18 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id F20D71956095; Wed, 5 Mar 2025 03:47:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146442; 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=MDXyivQbbnao2sqE7jinSEqJyRZAWAJfzIaOFfRSk2o=; b=Fha8Yyg7FQ/Q4ZvV72jwRHJRsSiX0IkBgk2zM2itGuE+HHS+TUk6ulU03qr5qV1FRUWYKV GYCT5mxn5zHgBMDHLkbzmWQUwwLoTWTJeTdkRAZ0BgMdFckMRWFi/3yr2G1tufVmyLY4Ee O1TOa2xEmoWMI4QqP9FrAV5ggdpzkyg= X-MC-Unique: ZhXVrGepMXSVBjtoXAzl1g-1 X-Mimecast-MFC-AGG-ID: ZhXVrGepMXSVBjtoXAzl1g_1741146438 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 17/57] docs/qapi-domain: add qapi:enum directive Date: Tue, 4 Mar 2025 22:45:26 -0500 Message-ID: <20250305034610.960147-18-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146473024019000 Content-Type: text/plain; charset="utf-8" Add the .. qapi:enum:: directive, object, and :qapi:enum:`name` cross-reference role. Add the :value name: field list for documenting Enum values. Of note, also introduce a new "type" role that is intended to be used by other QAPI object directives to cross-reference arbitrary QAPI type names, but will exclude commands, events, and modules from consideration. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 7531bdfbba7..66fdeec1d37 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -303,6 +303,23 @@ class QAPICommand(QAPIObject): ) =20 =20 +class QAPIEnum(QAPIObject): + """Description of a QAPI Enum.""" + + doc_field_types =3D QAPIObject.doc_field_types.copy() + doc_field_types.extend( + [ + # :value name: descr + GroupedField( + "value", + label=3D_("Values"), + names=3D("value",), + can_collapse=3DFalse, + ) + ] + ) + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -458,9 +475,14 @@ class QAPIDomain(Domain): # This table associates cross-reference object types (key) with an # ObjType instance, which defines the valid cross-reference roles # for each object type. + # + # e.g., the :qapi:type: cross-reference role can refer to enum, + # struct, union, or alternate objects; but :qapi:obj: can refer to + # anything. Each object also gets its own targeted cross-reference rol= e. object_types: Dict[str, ObjType] =3D { "module": ObjType(_("module"), "mod", "any"), "command": ObjType(_("command"), "cmd", "any"), + "enum": ObjType(_("enum"), "enum", "type", "any"), } =20 # Each of these provides a rST directive, @@ -468,6 +490,7 @@ class QAPIDomain(Domain): directives =3D { "module": QAPIModule, "command": QAPICommand, + "enum": QAPIEnum, } =20 # These are all cross-reference roles; e.g. @@ -476,6 +499,9 @@ class QAPIDomain(Domain): roles =3D { "mod": QAPIXRefRole(), "cmd": QAPIXRefRole(), + "enum": QAPIXRefRole(), + # reference any data type (excludes modules, commands, events) + "type": QAPIXRefRole(), "any": QAPIXRefRole(), # reference *any* type of QAPI object. } =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146488; cv=none; d=zohomail.com; s=zohoarc; b=WV7Ib+MUvUYr9RQYnwJ9n4ai6M1tQkXofCSG3Fmhgw7S1keie+nbGg3+Y1n9O+j3+kmcHgns2xJgUD13LWdY3ALsDixsGb0DfyD8kznxrVOoYHxsodTlpjUEDhSudnWA+1v0uW30cy0yQGpHk3h+ARSun/2e7xmPsvvBrBrxv/M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146488; 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=NOuPk1n5NCVsVAJdRRLy69vdaa01uAEYuIFG9s4IFjA=; b=k4RS49tB3R/qWVXd5I47WstQAY+UhzLaDZTQ8MO/f4xtAcVzsaK3XnidQjIvFacgkaPUKV4P+nxHSRrxC13DneBVOggfacSmL74KEwd3S+WinC/nS8pEJA5J8s5VVUnPxRAiXQyFrLcUYgUNnVdaTbubePjpU15LvjcquyNwY0E= 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 1741146488774116.20894317772093; Tue, 4 Mar 2025 19:48:08 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjS-0006lU-LO; Tue, 04 Mar 2025 22:47:44 -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 1tpfjL-0006Ub-OB for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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 1tpfjJ-00069y-Ti for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:35 -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-404-6C8053U2NQa9CfSb4GANlw-1; Tue, 04 Mar 2025 22:47:23 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 E1E7A18001CA; Wed, 5 Mar 2025 03:47:21 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id ED29B1956095; Wed, 5 Mar 2025 03:47:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146453; 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=NOuPk1n5NCVsVAJdRRLy69vdaa01uAEYuIFG9s4IFjA=; b=UUisPXd1g5m6fwM6ZtCH83JxjLzFfbESim+3CWslCm+mEicfxWvbO52oVO728ZjLT+mRGW rna2tUemJD4IDPpxm24ElgBoaV6WuadsAhQo+dg63AWIzibSRpnMKlINipTsuWk1N5hhzR 9/ikjQu46UH9MvVql4Jo5z2g3GnZx5o= X-MC-Unique: 6C8053U2NQa9CfSb4GANlw-1 X-Mimecast-MFC-AGG-ID: 6C8053U2NQa9CfSb4GANlw_1741146442 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 18/57] docs/qapi-domain: add qapi:alternate directive Date: Tue, 4 Mar 2025 22:45:27 -0500 Message-ID: <20250305034610.960147-19-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146489116019000 Content-Type: text/plain; charset="utf-8" Add the .. qapi:alternate:: directive, object, and qapi:alt:`name` cross-reference role. Add the "Choices:" field list for describing alternate choices. Like other field lists that reference QAPI types, a forthcoming commit will add cross-referencing support to this field. RFC: In the future, it would be nice to directly inline Alternates as part of the type information in the containing object (i.e. directly in arguments/members) - but that's a task for another series. For now, the branch "names" are documented just like qapidoc.py does, even though this information is superfluous for user documentation. Room for future improvement, but not now. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 66fdeec1d37..d4120fa5ac6 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -320,6 +320,23 @@ class QAPIEnum(QAPIObject): ) =20 =20 +class QAPIAlternate(QAPIObject): + """Description of a QAPI Alternate.""" + + doc_field_types =3D QAPIObject.doc_field_types.copy() + doc_field_types.extend( + [ + # :choice type name: descr + TypedField( + "choice", + label=3D_("Choices"), + names=3D("choice",), + can_collapse=3DFalse, + ), + ] + ) + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -483,6 +500,7 @@ class QAPIDomain(Domain): "module": ObjType(_("module"), "mod", "any"), "command": ObjType(_("command"), "cmd", "any"), "enum": ObjType(_("enum"), "enum", "type", "any"), + "alternate": ObjType(_("alternate"), "alt", "type", "any"), } =20 # Each of these provides a rST directive, @@ -491,6 +509,7 @@ class QAPIDomain(Domain): "module": QAPIModule, "command": QAPICommand, "enum": QAPIEnum, + "alternate": QAPIAlternate, } =20 # These are all cross-reference roles; e.g. @@ -500,6 +519,7 @@ class QAPIDomain(Domain): "mod": QAPIXRefRole(), "cmd": QAPIXRefRole(), "enum": QAPIXRefRole(), + "alt": QAPIXRefRole(), # reference any data type (excludes modules, commands, events) "type": QAPIXRefRole(), "any": QAPIXRefRole(), # reference *any* type of QAPI object. --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146707; cv=none; d=zohomail.com; s=zohoarc; b=EYqZOh2CwJdtWkAIZM0No6+TC5gscEyh0OUjR2aNrUOICyY2xz9ZN9+JKhDLxHC3PUACCOz08HprwVSoWiBdB+5EQbkGefOYIQhTe6wnu6DlV/FPI+stIbj36/Jcz4CxmcdkEMSdk9JSENM5G6S2oO8sfY9xi3oyKaRBKQRIhUo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146707; 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=cKh7S6y7TlOE3gN0+XEyzH/Ts/PyOKppfsmqiF377tU=; b=JmCDgGQzRkcXbC8cT3R/XEatPfZ2jsEwGxKeRhvhFxJ11EeFsEVTRWVPG1XRLvEpy+flbzkClMZ8nTgH7bovb2Tcp40jblr087gZHrH4EbsobXEqilckctGfLol74FoXR8e1maqS21bDyra/h2cufXgUWgvHEcYT8s3sJ0R8+RQ= 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 1741146707922634.2607378975416; Tue, 4 Mar 2025 19:51:47 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjd-0007Nd-Gg; Tue, 04 Mar 2025 22:47: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 1tpfjX-0006z8-KG for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:48 -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 1tpfjV-0006Bc-IS for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:47 -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-106-4ESW7ZWtNCii1MY3nrhRyg-1; Tue, 04 Mar 2025 22:47:26 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 6D1C518001CF; Wed, 5 Mar 2025 03:47:25 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 359EF1956095; Wed, 5 Mar 2025 03:47:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146465; 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=cKh7S6y7TlOE3gN0+XEyzH/Ts/PyOKppfsmqiF377tU=; b=J+MEIhYx0zgToDhoryjU87PEyrosUYuAB7DJbDofCn/rBg/2wuvAyfaY/h6VHjQr48utbp 7BGrJve+gL7NfmETq1hALjf9qiKsiI4ezusGMovQUHepwzRmFITnQ1opIYLV0sjZPW/t91 ByPeqn9y/UswLuYelgvwJO1eOLJ+zkU= X-MC-Unique: 4ESW7ZWtNCii1MY3nrhRyg-1 X-Mimecast-MFC-AGG-ID: 4ESW7ZWtNCii1MY3nrhRyg_1741146445 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 19/57] docs/qapi-domain: add qapi:event directive Date: Tue, 4 Mar 2025 22:45:28 -0500 Message-ID: <20250305034610.960147-20-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146709673019000 Content-Type: text/plain; charset="utf-8" Adds the .. qapi:event:: directive, object, and :qapi:event:`name` cross-referencing role. Adds the :memb type name: field list syntax for documenting event data members. As this syntax and phrasing will be shared with Structs and Unions as well, add the field list definition to a shared abstract class. As per usual, QAPI cross-referencing for types in the member field list will be added in a forthcoming commit. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d4120fa5ac6..d9c69af229d 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -337,6 +337,27 @@ class QAPIAlternate(QAPIObject): ) =20 =20 +class QAPIObjectWithMembers(QAPIObject): + """Base class for Events/Structs/Unions""" + + doc_field_types =3D QAPIObject.doc_field_types.copy() + doc_field_types.extend( + [ + # :member type name: descr + TypedField( + "member", + label=3D_("Members"), + names=3D("memb",), + can_collapse=3DFalse, + ), + ] + ) + + +class QAPIEvent(QAPIObjectWithMembers): + """Description of a QAPI Event.""" + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -499,6 +520,7 @@ class QAPIDomain(Domain): object_types: Dict[str, ObjType] =3D { "module": ObjType(_("module"), "mod", "any"), "command": ObjType(_("command"), "cmd", "any"), + "event": ObjType(_("event"), "event", "any"), "enum": ObjType(_("enum"), "enum", "type", "any"), "alternate": ObjType(_("alternate"), "alt", "type", "any"), } @@ -508,6 +530,7 @@ class QAPIDomain(Domain): directives =3D { "module": QAPIModule, "command": QAPICommand, + "event": QAPIEvent, "enum": QAPIEnum, "alternate": QAPIAlternate, } @@ -518,6 +541,7 @@ class QAPIDomain(Domain): roles =3D { "mod": QAPIXRefRole(), "cmd": QAPIXRefRole(), + "event": QAPIXRefRole(), "enum": QAPIXRefRole(), "alt": QAPIXRefRole(), # reference any data type (excludes modules, commands, events) --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146806; cv=none; d=zohomail.com; s=zohoarc; b=dqBckwOAaehtMJzqA5enqCo4KrreP7gwh4XZQ0EJ+GvOXeKkWFeSeL+osl+zF5YncGcm4MlbPmzv+gDSu0rBTxSG4maXQGkGw2Qqvpw+XeqCaSkrqSX7kldvoMn+PVOTS410OncMNWqId0D+WHwL69XywpPcNN5AKnxsnTTsq2s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146806; 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=BMoBJtmu8xBZdY3WStP+pjFcDUWJlVucMPHx8TbfcEY=; b=AG1dkqiCVJsDRwyt1WYlR+V7OC8EZBYwwjzBbe/bvtjfooYAmytu3mIJDXS3f3iZCQnl08oQ4mhp65U4aDu/p5VZ+M+X1j+Q1PgkpPlyltDKJMab5IKlqiUQsXNjElY59IJoc7cn+jgjEJbge1QvHeDquSGBlzs5wYhm3AiNFRg= 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 1741146806922318.4309756643911; Tue, 4 Mar 2025 19:53:26 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjZ-00073e-Lt; Tue, 04 Mar 2025 22:47:49 -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 1tpfjM-0006YM-R5 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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 1tpfjL-0006AB-3S for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:36 -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-12-Vu6sZ_aSO4GZgeAIPRl-CA-1; Tue, 04 Mar 2025 22:47:30 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 214721954203; Wed, 5 Mar 2025 03:47:29 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 08D641956095; Wed, 5 Mar 2025 03:47:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146454; 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=BMoBJtmu8xBZdY3WStP+pjFcDUWJlVucMPHx8TbfcEY=; b=iSaJgB2/GZ/wYaGdIG3j1niAVTtS27Ib7A4/LbgNKlBrRfRLDD6BLXlb8//Z0iVEGh/V3+ AMH3uBs4RZ3NQPXDkgbcbTNmfD4Nvi5Zm5+CGOH8604fJBgJCn0adnAiKmdObuHtADT6E6 6PVNEuUZGXW/SWnF0lEbTivI9eRj5ik= X-MC-Unique: Vu6sZ_aSO4GZgeAIPRl-CA-1 X-Mimecast-MFC-AGG-ID: Vu6sZ_aSO4GZgeAIPRl-CA_1741146449 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 20/57] docs/qapi-domain: add qapi:object directive Date: Tue, 4 Mar 2025 22:45:29 -0500 Message-ID: <20250305034610.960147-21-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146809453019100 Content-Type: text/plain; charset="utf-8" Adds the .. qapi:object:: directive, object, and :qapi:obj:`name` cross-referencing role. This directive is meant to document both structs and unions. As per usual, QAPI cross-referencing for types in the member field list will be added in a forthcoming commit. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d9c69af229d..fff5cca24cc 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -358,6 +358,10 @@ class QAPIEvent(QAPIObjectWithMembers): """Description of a QAPI Event.""" =20 =20 +class QAPIJSONObject(QAPIObjectWithMembers): + """Description of a QAPI Object: structs and unions.""" + + class QAPIModule(SphinxDirective): """ Directive to mark description of a new module. @@ -522,6 +526,7 @@ class QAPIDomain(Domain): "command": ObjType(_("command"), "cmd", "any"), "event": ObjType(_("event"), "event", "any"), "enum": ObjType(_("enum"), "enum", "type", "any"), + "object": ObjType(_("object"), "obj", "type", "any"), "alternate": ObjType(_("alternate"), "alt", "type", "any"), } =20 @@ -532,6 +537,7 @@ class QAPIDomain(Domain): "command": QAPICommand, "event": QAPIEvent, "enum": QAPIEnum, + "object": QAPIJSONObject, "alternate": QAPIAlternate, } =20 @@ -543,6 +549,7 @@ class QAPIDomain(Domain): "cmd": QAPIXRefRole(), "event": QAPIXRefRole(), "enum": QAPIXRefRole(), + "obj": QAPIXRefRole(), # specifically structs and unions. "alt": QAPIXRefRole(), # reference any data type (excludes modules, commands, events) "type": QAPIXRefRole(), --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146498; cv=none; d=zohomail.com; s=zohoarc; b=C581Iq7wrIG3tLjmDElqSqDLuCaOP/WcNJbX9hZd8bOCQk/p3S4AINif2t6cv4DlNIrYuwNo5SbuzW8lVx5qqaSohY4MbvRgjouPNtwvBnKjqK3P4fKxWu8lvl1DupJ2ZDYkYvpUc3dnoLDXpS/gW/QZE5V5bj97txlnnQXf1Ac= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146498; h=Content-Type: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=izzwoRTUjt1It3o5vsHMkCHTQ88Kc5AkVwfiriXCANY=; b=But+fG7K1xhyKrOjMFNhKsofz1wNAMUOFHX2LO/lXbWYf2W429vcpNiFeQs21JYapQgarTNbCrIvxmox1qXBnscdRFjuphR1UWBGyT6lgWaxviFx3O0aPodYfsokkynAXJeH/apFW+DzbgbyC2hi3H/hr9SgBHWKCsk5O33+LUY= 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 1741146498254765.6050185934034; Tue, 4 Mar 2025 19:48:18 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjY-0006y6-BA; Tue, 04 Mar 2025 22:47:48 -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 1tpfjP-0006lq-V0 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:40 -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 1tpfjO-0006Ai-4Y for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:39 -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-5RensmS4MWCQACtVwFjTDw-1; Tue, 04 Mar 2025 22:47:34 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 BB4B118001D4; Wed, 5 Mar 2025 03:47:32 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B09AF1956095; Wed, 5 Mar 2025 03:47:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146457; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=izzwoRTUjt1It3o5vsHMkCHTQ88Kc5AkVwfiriXCANY=; b=UK1r21JQ0GvP4xy79nXx6Vok73yb2irFDisuVnXimR6iKpZRx8im3v42BkP11Hwa7px1f8 NDjNzIMKAL5YnfCljvpJCzt76dRvV+BaWYpktJL69or+pWzdZzDRIVsxqnpe/RwzHpLCNj ch17iDxhfL+v5jWXxtVCFS7pXj8g8kk= X-MC-Unique: 5RensmS4MWCQACtVwFjTDw-1 X-Mimecast-MFC-AGG-ID: 5RensmS4MWCQACtVwFjTDw_1741146452 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow , Harmonie Snow Subject: [PATCH 21/57] docs/qapi-domain: add :deprecated: directive option Date: Tue, 4 Mar 2025 22:45:30 -0500 Message-ID: <20250305034610.960147-22-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146500747019100 Although "deprecated" is a feature (and *will* appear in the features list), add a special :deprecated: option to generate an eye-catch that makes this information very hard to miss. (The intent is to modify qapidoc.py to add this option whenever it detects that the features list attached to a definition contains the "deprecated" entry.) - RFC: Technically, this object-level option is un-needed and could be replaced with a standard content-level directive that e.g. qapidoc.py could insert at the beginning of the content block. I've done it here as an option to demonstrate how it would be possible to do. It's a matter of taste for "where" we feel like implementing it. One benefit of doing it this way is that we can create a single containing box to set CSS style options controlling the flow of multiple infoboxes. The other way to achieve that would be to create a directive that allows us to set multiple options instead, e.g.: .. qapi:infoboxes:: deprecated unstable or possibly: .. qapi:infoboxes:: :deprecated: :unstable: For now, I've left these as top-level QAPI object options. "Hey, it works." P.S., I outsourced the CSS ;) Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 25 +++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 26 ++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 965ecac54fd..3765cab1b20 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -208,3 +208,28 @@ div[class^=3D"highlight"] pre { color: inherit; } } + +/* QAPI domain theming */ + +.qapi-infopips { + margin-bottom: 1em; +} + +.qapi-infopip { + display: inline-block; + padding: 0em 0.5em 0em 0.5em; + margin: 0.25em; +} + +.qapi-deprecated { + background-color: #fffef5; + border: solid #fff176 6px; + font-weight: bold; + padding: 8px; + border-radius: 15px; + margin: 5px; +} + +.qapi-deprecated::before { + content: '=E2=9A=A0=EF=B8=8F '; +} diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index fff5cca24cc..1be59e36bdf 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -140,6 +140,7 @@ class QAPIObject(ObjectDescription[Signature]): "module": directives.unchanged, # Override contextual module = name # These are QAPI originals: "since": since_validator, + "deprecated": directives.flag, } ) =20 @@ -253,6 +254,31 @@ def add_target_and_index( ("single", indextext, node_id, "", None) ) =20 + def _add_infopips(self, contentnode: addnodes.desc_content) -> None: + # Add various eye-catches and things that go below the signature + # bar, but precede the user-defined content. + infopips =3D nodes.container() + infopips.attributes["classes"].append("qapi-infopips") + + def _add_pip(source: str, content: str, classname: str) -> None: + node =3D nodes.container(source) + node.append(nodes.Text(content)) + node.attributes["classes"].extend(["qapi-infopip", classname]) + infopips.append(node) + + if "deprecated" in self.options: + _add_pip( + ":deprecated:", + f"This {self.objtype} is deprecated.", + "qapi-deprecated", + ) + + if infopips.children: + contentnode.insert(0, infopips) + + def transform_content(self, content_node: addnodes.desc_content) -> No= ne: + self._add_infopips(content_node) + def _toc_entry_name(self, sig_node: desc_signature) -> str: # This controls the name in the TOC and on the sidebar. =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146534; cv=none; d=zohomail.com; s=zohoarc; b=M61JAzzfmSlLYZdMNg7BHF3gSeHQDr6RRDneuNgBrNoCHoW32egK8avNPw1MScg3z+pnnilO8UItTW5xWT7l/cREL2+r5KNIWoDB8m/g+lwK1fcRV8a7sXbYGWCLX596/9HlPzrF/oT+FY0fOgULXPN/qiHsR9VtfT+Gxdzd5s0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146534; h=Content-Type: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=YAp2bFFAa9kq9B6wvgXdolIRvENLUMiUD/N5oF6tkdM=; b=Vd6qCVwciEyiveczxw/xw7KfSSpIK7q3oUgZVpuTnH+Z3ZKxAy2bWt3yM3EwAvNwmrWq+YrqRE/zuY3ZpYGHEsvBvHzyONPWIeh3Ul6dyLutNTCI3eHPWpgJ9bC8NYi+7OD2zM3Y68ggqQbfwfa3sNca/JQbe/GLeWTKu2MtgB0= 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 1741146534651142.8287751976759; Tue, 4 Mar 2025 19:48:54 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjb-0007B6-03; Tue, 04 Mar 2025 22:47:51 -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 1tpfjX-0006y8-6g for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:47 -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 1tpfjV-0006BY-3P for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:46 -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-33-9kx_7q8bNdCL5nV3QNW9_A-1; Tue, 04 Mar 2025 22:47:37 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 0590B193585F; Wed, 5 Mar 2025 03:47:36 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C47881956095; Wed, 5 Mar 2025 03:47:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146464; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=YAp2bFFAa9kq9B6wvgXdolIRvENLUMiUD/N5oF6tkdM=; b=hxTfdd7fuMG/mfuAyNL7GbEpj73V7CWomyVlD4IBpP1B+0N/DBkOs6Gn8JWWWVZJJ3cGyb Qn7cAPDtgwtJUMwBfejTjchSJl5MnaM/fpYJhb8l1morgfqTes2RmPAeh1uzTGUdwA+RIk jbqTftOYDeLhBCc8i465qpznhTOD+v8= X-MC-Unique: 9kx_7q8bNdCL5nV3QNW9_A-1 X-Mimecast-MFC-AGG-ID: 9kx_7q8bNdCL5nV3QNW9_A_1741146456 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow , Harmonie Snow Subject: [PATCH 22/57] docs/qapi-domain: add :unstable: directive option Date: Tue, 4 Mar 2025 22:45:31 -0500 Message-ID: <20250305034610.960147-23-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146536767019100 Although "unstable" is a feature (and *will* appear in the features list), add a special :unstable: option to generate an eye-catch that makes this information very hard to miss. (The intent is to modify qapidoc.py to add this option whenever it detects that the features list attached to a definition contains the "unstable" entry.) RFC: Same comments as last patch. Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 6 +++++- docs/sphinx/qapi_domain.py | 8 ++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 3765cab1b20..5f58f1d5246 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -221,7 +221,7 @@ div[class^=3D"highlight"] pre { margin: 0.25em; } =20 -.qapi-deprecated { +.qapi-deprecated,.qapi-unstable { background-color: #fffef5; border: solid #fff176 6px; font-weight: bold; @@ -230,6 +230,10 @@ div[class^=3D"highlight"] pre { margin: 5px; } =20 +.qapi-unstable::before { + content: '=F0=9F=9A=A7 '; +} + .qapi-deprecated::before { content: '=E2=9A=A0=EF=B8=8F '; } diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 1be59e36bdf..ef4fa978a3a 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -141,6 +141,7 @@ class QAPIObject(ObjectDescription[Signature]): # These are QAPI originals: "since": since_validator, "deprecated": directives.flag, + "unstable": directives.flag, } ) =20 @@ -273,6 +274,13 @@ def _add_pip(source: str, content: str, classname: str= ) -> None: "qapi-deprecated", ) =20 + if "unstable" in self.options: + _add_pip( + ":unstable:", + f"This {self.objtype} is unstable/experimental.", + "qapi-unstable", + ) + if infopips.children: contentnode.insert(0, infopips) =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146733; cv=none; d=zohomail.com; s=zohoarc; b=OpAektXNQysaqLaQApXzfTn+X66NFT750ZiJuuO8Cpjk//JPqdzO7iTZomn31vPnmx77MuCoALXAP52wwZ/qODlUjTMjFnS2IJwL1xdwVh3nHCInD/oaOyvzHrbv/Bd7NETd4K80MU5kC/33YMeVb0lzbzm0LWd6q3TwhVA1L+Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146733; h=Content-Type: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=jWa8GJCduxWshfwUn3fnT7aU0+/ceVS4gTer/ZEqj08=; b=IaVV4i51jqVsBOgcq6wipvBPn8ZDoaOSBmklN1WqdIeBgvW8DLsUyDquZURD0f7GdMY3iJO5Lyv501yvKtOHyet2iQwD1WOx3n6Mf+6Hhq/SnVPow3tNccPAx2OjskpzhF0AwieRD4Vk1MIIz6TNGrTvqxoaZAresCu4UAZ0vu0= 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 174114673324928.64546323858599; Tue, 4 Mar 2025 19:52:13 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjh-0007lq-VE; Tue, 04 Mar 2025 22:47: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 1tpfjf-0007Xo-Mu for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:55 -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 1tpfje-0006D7-0P for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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-411-wrR_q2RuPKW30UDgkHrR1g-1; Tue, 04 Mar 2025 22:47:41 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 0E8DE1800258; Wed, 5 Mar 2025 03:47:40 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6DC6D1956095; Wed, 5 Mar 2025 03:47:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146473; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jWa8GJCduxWshfwUn3fnT7aU0+/ceVS4gTer/ZEqj08=; b=YUaxrCI6Cxve2TxdK1/Ers3UOSvNP+sIpoj7W4SwyTRqWDJ4IVQHbDMNWPiv4iez8XuVZl h7AQk2tgQTtSuNzOZ/Hm4MS+yIkOktesJtvTqACE9DsJ/XRDOlG9tQOYf0ehW8jB5S3Zip V/ewtVpTzCrzOzuRdSUjqlKHm3/7wW0= X-MC-Unique: wrR_q2RuPKW30UDgkHrR1g-1 X-Mimecast-MFC-AGG-ID: wrR_q2RuPKW30UDgkHrR1g_1741146460 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow , Harmonie Snow Subject: [PATCH 23/57] docs/qapi-domain: add :ifcond: directive option Date: Tue, 4 Mar 2025 22:45:32 -0500 Message-ID: <20250305034610.960147-24-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146735498019100 Add a special :ifcond: option that allows us to annotate the definition-level conditionals. RFC: This patch renders IFCOND information in two places, because I'm undecided about how to style this information. One option is in the signature bar, and another option is in an eye-catch, like :deprecated: or :unstable:. A benefit to having this be a directive option is that we can put it in the signature bar, the QAPI index, etc. However, if we merely want it in the content section, a directive would work just as well, e.g. ".. qapi:ifcond:: CONFIG_LINUX". (Though, having it be in the same containing box as the unstable/ifcond boxes might require some extra fiddling/post-processing to achieve. Generally, the less docutils tree muddling I have to do, the happier I am.) The syntax of the argument is currently undefined, but it is possible to parse it back down into constituent parts to avoid applying literal formatting to "AND" or "&&" or whichever syntax we formalize. (Or, in the future, applying cross-reference links to the config values for additional reading on some of those build options. Not for this series.) "Vote now on your phones!" Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 13 +++++++++ docs/sphinx/qapi_domain.py | 39 ++++++++++++++++++++++++-- 2 files changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 5f58f1d5246..3fd326613d9 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -237,3 +237,16 @@ div[class^=3D"highlight"] pre { .qapi-deprecated::before { content: '=E2=9A=A0=EF=B8=8F '; } + +.qapi-ifcond::before { + /* gaze ye into the crystal ball to determine feature availability */ + content: '=F0=9F=94=AE '; +} + +.qapi-ifcond { + background-color: #f9f5ff; + border: solid #dac2ff 6px; + padding: 8px; + border-radius: 15px; + margin: 5px; +} diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index ef4fa978a3a..c75b0e6e22d 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -16,6 +16,7 @@ NamedTuple, Optional, Tuple, + Union, cast, ) =20 @@ -140,6 +141,7 @@ class QAPIObject(ObjectDescription[Signature]): "module": directives.unchanged, # Override contextual module = name # These are QAPI originals: "since": since_validator, + "ifcond": directives.unchanged, "deprecated": directives.flag, "unstable": directives.flag, } @@ -167,6 +169,22 @@ def get_signature_suffix(self) -> List[nodes.Node]: """Returns a suffix to put after the object name in the signature.= """ ret: List[nodes.Node] =3D [] =20 + if "ifcond" in self.options: + ret +=3D [ + SpaceNode(" "), + nodes.inline( + self.options["ifcond"], + "", + nodes.Text("["), + nodes.literal("", "#if"), + SpaceNode(" "), + nodes.literal( + self.options["ifcond"], self.options["ifcond"] + ), + nodes.Text("]"), + ), + ] + if "since" in self.options: ret +=3D [ SpaceNode(" "), @@ -261,9 +279,14 @@ def _add_infopips(self, contentnode: addnodes.desc_con= tent) -> None: infopips =3D nodes.container() infopips.attributes["classes"].append("qapi-infopips") =20 - def _add_pip(source: str, content: str, classname: str) -> None: + def _add_pip( + source: str, content: Union[str, List[nodes.Node]], classname:= str + ) -> None: node =3D nodes.container(source) - node.append(nodes.Text(content)) + if isinstance(content, str): + node.append(nodes.Text(content)) + else: + node.extend(content) node.attributes["classes"].extend(["qapi-infopip", classname]) infopips.append(node) =20 @@ -281,6 +304,18 @@ def _add_pip(source: str, content: str, classname: str= ) -> None: "qapi-unstable", ) =20 + if self.options.get("ifcond", ""): + ifcond =3D self.options["ifcond"] + _add_pip( + f":ifcond: {ifcond}", + [ + nodes.emphasis("", "Availability"), + nodes.Text(": "), + nodes.literal(ifcond, ifcond), + ], + "qapi-ifcond", + ) + if infopips.children: contentnode.insert(0, infopips) =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146498; cv=none; d=zohomail.com; s=zohoarc; b=Ies7MotBMOEY4r+k1fga3f1blZQZ13Ll42xD1mIKC3bALJVh8VNTtO20AKJBM8oNDt6f1ES8OTM4SaeQftp8znl0DJBt6lWc0Q23SG/iXf/ml9ZgJ+UqNZs+ueaBCvknd8DLxke9GZqIFfZi6+zAthypD8+MjW95kYkJdmekFTI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146498; 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=TXoyfVbNpb8ax7H+NR9rNWEed6MoOiVecpGSNrsEMCY=; b=NiReGb3EBDfpj69QrEQeVCh1PHVbxRdmCM/sVuUJ1IFYARg0agjK7E+wP+b8EYD7AK2+5smzoigLKKFsLKKuh067sUhU869n0KB7VmnzORh0dIIhH2oIp82NQY8ZTJmFk5iyKrWH5F7/Gg6I8GaPjrNLMpDDuuiiFYHXw+Jv7HQ= 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 1741146498007303.92014141088305; Tue, 4 Mar 2025 19:48:18 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfji-0007mH-QZ; Tue, 04 Mar 2025 22:47: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 1tpfjg-0007c6-I2 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:56 -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 1tpfje-0006DB-FU for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:56 -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-207-7W9l2sRWN3qiSKqZH2puJg-1; Tue, 04 Mar 2025 22:47:44 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 AF0721954185; Wed, 5 Mar 2025 03:47:43 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id BF4B71956095; Wed, 5 Mar 2025 03:47:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146473; 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=TXoyfVbNpb8ax7H+NR9rNWEed6MoOiVecpGSNrsEMCY=; b=XSHS6On3EnhnsgdH8CYfFoLmdpRo95m2YJQynw5KE9UgDr1bT0dE6jbnL0DEOuuONzgAYb zApjjRJQiqd5nN9EqpknwMkrR3Mic2lknQ9eZwaf91hUTc4VZeEGdozLPMWfJbAAOSDjxw wNhhZkOMZ9XnccnwYxwI7+1hwisKpdM= X-MC-Unique: 7W9l2sRWN3qiSKqZH2puJg-1 X-Mimecast-MFC-AGG-ID: 7W9l2sRWN3qiSKqZH2puJg_1741146463 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 24/57] docs/qapi-domain: add warnings for malformed field lists Date: Tue, 4 Mar 2025 22:45:33 -0500 Message-ID: <20250305034610.960147-25-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146499318019000 Content-Type: text/plain; charset="utf-8" Normally, Sphinx will silently fall back to its standard field list processing if it doesn't match one of your defined fields. A lot of the time, that's not what we want - we want to be warned if we goof something up. For instance, the canonical argument field list form is: :arg type name: descr This form is captured by Sphinx and transformed so that the field label will become "Arguments:". It's possible to omit the type name and descr and still have it be processed correctly. However, if you omit the type name, Sphinx no longer recognizes it: :arg: this is not recognized. This will turn into an arbitrary field list entry whose label is "Arg:", and it otherwise silently fails. You may also see failures for doing things like using :values: instead of :value:, or :errors: instead of :error:, and so on. It's also case sensitive, and easy to trip up. Add a validator that guarantees all field list entries that are the direct child of an ObjectDescription use only recognized forms of field lists, and emit a warning (treated as error by default in most build configurations) whenever we detect one that is goofed up. However, there's still benefit to allowing arbitrary fields -- they are after all not a Sphinx invention, but perfectly normal docutils syntax. Create an allow list for known spellings we don't mind letting through, but warn against anything else. Signed-off-by: John Snow --- docs/conf.py | 9 +++++ docs/sphinx/qapi_domain.py | 77 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 49d9de894c0..a3f9fa63d94 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -153,6 +153,15 @@ with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: rst_epilog +=3D f.read() =20 + +# Normally, the QAPI domain is picky about what field lists you use to +# describe a QAPI entity. If you'd like to use arbitrary additional +# fields in source documentation, add them here. +qapi_allowed_fields =3D { + "see also", +} + + # -- Options for HTML output ---------------------------------------------- =20 # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index c75b0e6e22d..6eaf8ce92b4 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -52,6 +52,19 @@ logger =3D logging.getLogger(__name__) =20 =20 +def _unpack_field( + field: nodes.Node, +) -> Tuple[nodes.field_name, nodes.field_body]: + """ + docutils helper: unpack a field node in a type-safe manner. + """ + assert isinstance(field, nodes.field) + assert len(field.children) =3D=3D 2 + assert isinstance(field.children[0], nodes.field_name) + assert isinstance(field.children[1], nodes.field_body) + return (field.children[0], field.children[1]) + + class ObjectEntry(NamedTuple): docname: str node_id: str @@ -319,9 +332,67 @@ def _add_pip( if infopips.children: contentnode.insert(0, infopips) =20 + def _validate_field(self, field: nodes.field) -> None: + """Validate field lists in this QAPI Object Description.""" + name, _ =3D _unpack_field(field) + allowed_fields =3D set(self.env.app.config.qapi_allowed_fields) + + field_label =3D name.astext() + if ( + re.match(r"\[\S+ =3D \S+\]", field_label) + or field_label in allowed_fields + ): + # okie-dokey. branch entry or known good allowed name. + return + + try: + # split into field type and argument (if provided) + # e.g. `:arg type name: descr` is + # field_type =3D "arg", field_arg =3D "type name". + field_type, field_arg =3D field_label.split(None, 1) + except ValueError: + # No arguments provided + field_type =3D field_label + field_arg =3D "" + + typemap =3D self.get_field_type_map() + if field_type in typemap: + # This is a special docfield, yet-to-be-processed. Catch + # correct names, but incorrect arguments. This mismatch WILL + # cause Sphinx to render this field incorrectly (without a + # warning), which is never what we want. + typedesc =3D typemap[field_type][0] + if typedesc.has_arg !=3D bool(field_arg): + msg =3D f"docfield field list type {field_type!r} " + if typedesc.has_arg: + msg +=3D "requires an argument." + else: + msg +=3D "takes no arguments." + logger.warning(msg, location=3Dfield) + else: + # This is unrecognized entirely. It's valid rST to use + # arbitrary fields, but let's ensure the documentation + # writer has done this intentionally. + valid =3D ", ".join(sorted(set(typemap) | allowed_fields)) + msg =3D ( + f"Unrecognized field list name {field_label!r}.\n" + f"Valid fields for qapi:{self.objtype} are: {valid}\n" + "\n" + "If this usage is intentional, please add it to " + "'qapi_allowed_fields' in docs/conf.py." + ) + logger.warning(msg, location=3Dfield) + def transform_content(self, content_node: addnodes.desc_content) -> No= ne: self._add_infopips(content_node) =20 + # Validate field lists. + for child in content_node: + if isinstance(child, nodes.field_list): + for field in child.children: + assert isinstance(field, nodes.field) + self._validate_field(field) + def _toc_entry_name(self, sig_node: desc_signature) -> str: # This controls the name in the TOC and on the sidebar. =20 @@ -817,6 +888,12 @@ def resolve_any_xref( =20 def setup(app: Sphinx) -> Dict[str, Any]: app.setup_extension("sphinx.directives") + app.add_config_value( + "qapi_allowed_fields", + set(), + "env", # Setting impacts parsing phase + types=3Dset, + ) app.add_domain(QAPIDomain) =20 return { --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146531; cv=none; d=zohomail.com; s=zohoarc; b=dkNoB+n+ZYBAGb+7xrPN0Du/EaJlr7rocGD5yktivOWGbktDC4pko5ZtdUN91o8dIJwCa6M8prwNGipnjevdlNjJn08VXUFzGBeOwXaFTfFfGWX1aojR29yn7Z6jGthAC6OXIJLAYCmBbTfJvBFPcakZnfREbVJ30Ia/sa3zJ98= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146531; 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=bCfOGBdJQwnF5xt02pbv4fzYOIJ9eH+7LDoB69oghKg=; b=T1wljgvJQiZWTgcThCM3xykcL36uYesf3Xa1yxbkrbWsJ3Nljb44F4vEtFL4SOA/xcXQeh01EVf3jNoy4eM5IaaOkHBZx7/r2tI4gtFrapzAeKBjaXM1nXLI7ThqQVC1B7bc88YAr0weo/tZx77HnQgfTK/cwTA74xffPjZ9kpY= 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 1741146531009449.8239980500732; Tue, 4 Mar 2025 19:48:51 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjf-0007Xe-Ue; Tue, 04 Mar 2025 22:47:56 -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 1tpfjc-0007Mx-P5 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47: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 1tpfja-0006Cc-JQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:47:52 -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-505-1WX9GH9zO2CR64c-kSLR3w-1; Tue, 04 Mar 2025 22:47:48 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 8B8331954191; Wed, 5 Mar 2025 03:47:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 271841956095; Wed, 5 Mar 2025 03:47:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146469; 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=bCfOGBdJQwnF5xt02pbv4fzYOIJ9eH+7LDoB69oghKg=; b=ZqK2fgWFuyueX7glf+II4NNnWoaT1FibWaVvK3JdmXFYNBjy9+TsiAzddTxV8+GFIPsUBu 4BozdvGWqhZEGXFc/flCunENqHtGuEcO7XK9arNVRl1EuKCu0q3P6Ns8Vxgqk/Y//ibpsz g8grWS3+BxBPzY8puJ1DxwLBGZKpuqo= X-MC-Unique: 1WX9GH9zO2CR64c-kSLR3w-1 X-Mimecast-MFC-AGG-ID: 1WX9GH9zO2CR64c-kSLR3w_1741146467 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 25/57] docs/qapi-domain: add type cross-refs to field lists Date: Tue, 4 Mar 2025 22:45:34 -0500 Message-ID: <20250305034610.960147-26-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146533208019000 Content-Type: text/plain; charset="utf-8" This commit, finally, adds cross-referencing support to various field lists; modeled tightly after Sphinx's own Python domain code. Cross-referencing support is added to type names provided to :arg:, :memb:, :returns: and :choice:. :feat:, :error: and :value:, which do not take type names, do not support this syntax. The general syntax is simple: :arg TypeName ArgName: Lorem Ipsum ... The domain will transform TypeName into :qapi:type:`TypeName` in this basic case, and also apply the ``literal`` decoration to indicate that this is a type cross-reference. For optional arguments, the special "?" suffix is used. Because "*" has special meaning in rST that would cause parsing errors, we elect to use "?" instead. The special syntax processing strips this character from the end of any type name argument and will append ", optional" to the rendered output, applying the cross-reference only to the actual type name. The intent here is that the actual syntax in doc-blocks need not change; but e.g. qapidoc.py will need to process and transform "@arg foo lorem ipsum" into ":arg type? foo: lorem ipsum" based on the schema information. Therefore, nobody should ever actually witness this intermediate syntax unless they are writing manual documentation or the doc transmogrifier breaks. For array arguments, type names can similarly be surrounded by "[]", which are stripped off and then re-appended outside of the cross-reference. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 6eaf8ce92b4..753e07024f5 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -2,6 +2,9 @@ QAPI domain extension. """ =20 +# The best laid plans of mice and men, ... +# pylint: disable=3Dtoo-many-lines + from __future__ import annotations =20 import re @@ -119,6 +122,28 @@ def process_link( =20 return title, target =20 + def result_nodes( + self, + document: nodes.document, + env: BuildEnvironment, + node: Element, + is_ref: bool, + ) -> Tuple[List[nodes.Node], List[nodes.system_message]]: + + # node here is the pending_xref node (or whatever nodeclass was + # configured at XRefRole class instantiation time). + results: List[nodes.Node] =3D [node] + + if node.get("qapi:array"): + results.insert(0, nodes.literal("[", "[")) + results.append(nodes.literal("]", "]")) + + if node.get("qapi:optional"): + results.append(nodes.Text(", ")) + results.append(nodes.emphasis("?", "optional")) + + return results, [] + =20 def since_validator(param: str) -> str: """ @@ -423,6 +448,7 @@ class QAPICommand(QAPIObject): "argument", label=3D_("Arguments"), names=3D("arg",), + typerolename=3D"type", can_collapse=3DFalse, ), # :error: descr @@ -436,6 +462,7 @@ class QAPICommand(QAPIObject): GroupedField( "returnvalue", label=3D_("Returns"), + rolename=3D"type", names=3D("return", "returns"), can_collapse=3DTrue, ), @@ -471,6 +498,7 @@ class QAPIAlternate(QAPIObject): "choice", label=3D_("Choices"), names=3D("choice",), + typerolename=3D"type", can_collapse=3DFalse, ), ] @@ -488,6 +516,7 @@ class QAPIObjectWithMembers(QAPIObject): "member", label=3D_("Members"), names=3D("memb",), + typerolename=3D"type", can_collapse=3DFalse, ), ] --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146589; cv=none; d=zohomail.com; s=zohoarc; b=ZKZz9fNJ6jgGne1/3a9A6sUpLi+TtPmM+QEcjx6Wv0XAvwO+LC5O9WfczywcHy1c+2D3Q6RM4C+G4+Y+6Jw5nlJfZWl9jC4/Qt1yR6AxujrmPmWbQIAPTUf9rZ1FUFRlhybclXn6klgO3tfTghzit4xha1UQFLQy/UTCrjf2GBg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146589; 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=M4NWkQ4ouYUL+mKJBAl/nb9/STXk2k++zJ8lVadQp84=; b=GgC2XHVNd7ousMudc8Z8oUjmc8wwP96pzd9cgqZ3k5eqCxhwor5HdImB9G+tAWQiZtWTWzxJ3JaAntZXn0fohvpydllXnnWdRA9Fhj4yuAdqFVsFo9hi8osYD6mxTyUg8WCZaqeNuk8+nMthoXn/2drVlsGmTqlMmsHt4YC/2HE= 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 1741146589180479.1900451118885; Tue, 4 Mar 2025 19:49:49 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk0-0000pq-9v; Tue, 04 Mar 2025 22:48:16 -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 1tpfjv-0000gT-PJ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:11 -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 1tpfju-0006FE-1B for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:11 -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-328-089OL6oYPDeXDB1PT4Pt_w-1; Tue, 04 Mar 2025 22:47:57 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 D2F781954218; Wed, 5 Mar 2025 03:47:51 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 261031956095; Wed, 5 Mar 2025 03:47:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146487; 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=M4NWkQ4ouYUL+mKJBAl/nb9/STXk2k++zJ8lVadQp84=; b=GR2NAovtL7xolgbBRXIUiTSpXQdUiwbtDk6fh6gj2MVliBwDJ3ZggkT+6zWjdpmFlUi9Zq NHYDEC8Cjc9qXGj3jAZz47lzHgj/H3xjzkmuLrCGFnMhQx0Cb8l9nEXlX2jpvDwaOcWL4X Z63SgVWRORoILK/XSaGgs1sUVIapCaA= X-MC-Unique: 089OL6oYPDeXDB1PT4Pt_w-1 X-Mimecast-MFC-AGG-ID: 089OL6oYPDeXDB1PT4Pt_w_1741146471 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow , Harmonie Snow Subject: [PATCH 26/57] docs/qapi-domain: add CSS styling Date: Tue, 4 Mar 2025 22:45:35 -0500 Message-ID: <20250305034610.960147-27-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146590867019100 Content-Type: text/plain; charset="utf-8" Improve the general look and feel of generated QAPI docs. Attempt to limit line lengths to offer a more comfortable measure on maximized windows, and improve some margin and spacing for field lists. Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 56 +++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 3fd326613d9..92f395054a8 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -18,8 +18,8 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, = h5, h6, legend { =20 .rst-content dl:not(.docutils) dt { border-top: none; - border-left: solid 3px #ccc; - background-color: #f0f0f0; + border-left: solid 5px #bcc6d2; + background-color: #eaedf1; color: black; } =20 @@ -211,6 +211,18 @@ div[class^=3D"highlight"] pre { =20 /* QAPI domain theming */ =20 +/* most content in a qapi object definition should not eclipse about + 80ch, but nested field lists are explicitly exempt due to their + two-column nature */ +.qapi dd *:not(dl) { + max-width: 80ch; +} + +/* but the content column itself should still be less than ~80ch. */ +.qapi .field-list dd { + max-width: 80ch; +} + .qapi-infopips { margin-bottom: 1em; } @@ -250,3 +262,43 @@ div[class^=3D"highlight"] pre { border-radius: 15px; margin: 5px; } + +/* code blocks */ +.qapi div[class^=3D"highlight"] { + width: fit-content; + background-color: #fffafd; + border: 2px solid #ffe1f3; +} + +/* note, warning, etc. */ +.qapi .admonition { + width: fit-content; +} + +/* pad the top of the field-list so the text doesn't start directly at + the top border; primarily for the field list labels, but adjust the + field bodies as well for parity. */ +dl.field-list > dt:first-of-type, dl.field-list > dd:first-of-type { + padding-top: 0.3em; +} + +dl.field-list > dt:last-of-type, dl.field-list > dd:last-of-type { + padding-bottom: 0.3em; +} + +/* pad the field list labels so they don't crash into the border */ +dl.field-list > dt { + padding-left: 0.5em; + padding-right: 0.5em; +} + +/* Add a little padding between field list sections */ +dl.field-list > dd:not(:last-child) { + padding-bottom: 1em; +} + +/* Sphinx 3.x: unresolved xrefs */ +.rst-content *:not(a) > code.xref { + font-weight: 400; + color: #333333; +} --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146502; cv=none; d=zohomail.com; s=zohoarc; b=BMo6Rkl91soPVwybqg6ZSmqUfTxpZQSolR1wwkhR9huEzTdCRNMt5voTm1MG3lvNdKN28SGB5VG8Hp71+LcS0ME1FNKAcM0pgxOOdUer3v7UmJ+NitDPxo7C79Sicf5k3bMiJ5unvRt0EOMTheGuROa6I2jjjk6flNvTnwg1TMo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146502; 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=XnCJfW+biu+m4w15XD6/6V9QzgBV8sqOeeCt9NGl4Zo=; b=VMDxHbuQiigWbnKAYk+wA3bUCLzAuSRZI/aaUYKJ92TwGPZVOU9/0AvnGYrywdXEriU9LlmeJnTVdyxqizghgxO6HYBVDSHur4/pylpbL4RP+EYrDXnv9xy61/H6okogMcESsJT7jsJ9oq8b6fQ5XROaz4zPAj/eAwKqgblUls0= 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 1741146502118107.84680962500613; Tue, 4 Mar 2025 19:48:22 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfjo-0008Sc-Rb; Tue, 04 Mar 2025 22:48: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 1tpfjm-0008Cu-01 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:02 -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 1tpfjj-0006Du-Sg for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:01 -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-442-9qIvw5y-OMajbyRkzJul9Q-1; Tue, 04 Mar 2025 22:47:55 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 C451919039CE; Wed, 5 Mar 2025 03:47:54 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6FF4E1956095; Wed, 5 Mar 2025 03:47:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146479; 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=XnCJfW+biu+m4w15XD6/6V9QzgBV8sqOeeCt9NGl4Zo=; b=gTvfS2+2NR0dSteE2VYNwmDOYshLaFYkr5ZQKh/e2eVKO/tR4Rq2ud6Gl4jXDtF9l/8Gg6 8+lf227yOQ/f718u8v+3nnnfz1+X6o4bvVhHpa7EETHDq6On9tsIL5ODtIr4ta3CDAsqvu +90Kq45oncu7Qwlw1wkI9NR+QTYHfF4= X-MC-Unique: 9qIvw5y-OMajbyRkzJul9Q-1 X-Mimecast-MFC-AGG-ID: 9qIvw5y-OMajbyRkzJul9Q_1741146474 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 27/57] docs/qapi-domain: add XREF compatibility goop for Sphinx < 4.1 Date: Tue, 4 Mar 2025 22:45:36 -0500 Message-ID: <20250305034610.960147-28-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146503151019000 Content-Type: text/plain; charset="utf-8" Sphinx < 4.1 handles cross-references ... differently. Factor out and isolate the compatibility goop we need to make cross references work properly in old versions of Sphinx. Yes, it's ugly. Yes, it works. No, I don't want to talk about it. Understand that this patch exists because of the overflowing love in my heart. Signed-off-by: John Snow --- docs/sphinx/compat.py | 129 ++++++++++++++++++++++++++++++++++++- docs/sphinx/qapi_domain.py | 24 ++++--- 2 files changed, 142 insertions(+), 11 deletions(-) diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py index 1f9f1f42ef7..7e8d72c9b1f 100644 --- a/docs/sphinx/compat.py +++ b/docs/sphinx/compat.py @@ -2,14 +2,32 @@ Sphinx cross-version compatibility goop """ =20 -from typing import Callable +import re +from typing import ( + Any, + Callable, + Optional, + Type, +) =20 +from docutils import nodes from docutils.nodes import Element, Node, Text =20 import sphinx from sphinx import addnodes -from sphinx.util.docutils import SphinxDirective, switch_source_input +from sphinx.environment import BuildEnvironment +from sphinx.roles import XRefRole +from sphinx.util import docfields +from sphinx.util.docutils import ( + ReferenceRole, + SphinxDirective, + switch_source_input, +) from sphinx.util.nodes import nested_parse_with_titles +from sphinx.util.typing import TextlikeNode + + +MAKE_XREF_WORKAROUND =3D sphinx.version_info[:3] < (4, 1, 0) =20 =20 SpaceNode: Callable[[str], Node] @@ -46,3 +64,110 @@ def nested_parse(directive: SphinxDirective, content_no= de: Element) -> None: nested_parse_with_titles( directive.state, directive.content, content_node ) + + +# ########################################### +# xref compatibility hacks for Sphinx < 4.1 # +# ########################################### + +# When we require >=3D Sphinx 4.1, the following function and the +# subsequent 3 compatibility classes can be removed. Anywhere in +# qapi_domain that uses one of these Compat* types can be switched to +# using the garden-variety lib-provided classes with no trickery. + + +def _compat_make_xref( # pylint: disable=3Dunused-argument + self: sphinx.util.docfields.Field, + rolename: str, + domain: str, + target: str, + innernode: Type[TextlikeNode] =3D addnodes.literal_emphasis, + contnode: Optional[Node] =3D None, + env: Optional[BuildEnvironment] =3D None, + inliner: Any =3D None, + location: Any =3D None, +) -> Node: + """ + Compatibility workaround for Sphinx versions prior to 4.1.0. + + Older sphinx versions do not use the domain's XRefRole for parsing + and formatting cross-references, so we need to perform this magick + ourselves to avoid needing to write the parser/formatter in two + separate places. + + This workaround isn't brick-for-brick compatible with modern Sphinx + versions, because we do not have access to the parent directive's + state during this parsing like we do in more modern versions. + + It's no worse than what pre-Sphinx 4.1.0 does, so... oh well! + """ + + # Yes, this function is gross. Pre-4.1 support is a miracle. + # pylint: disable=3Dtoo-many-locals + + assert env + # Note: Sphinx's own code ignores the type warning here, too. + if not rolename: + return contnode or innernode(target, target) # type: ignore[call-= arg] + + # Get the role instance, but don't *execute it* - we lack the + # correct state to do so. Instead, we'll just use its public + # methods to do our reference formatting, and emulate the rest. + role =3D env.get_domain(domain).roles[rolename] + assert isinstance(role, XRefRole) + + # XRefRole features not supported by this compatibility shim; + # these were not supported in Sphinx 3.x either, so nothing of + # value is really lost. + assert not target.startswith("!") + assert not re.match(ReferenceRole.explicit_title_re, target) + assert not role.lowercase + assert not role.fix_parens + + # Code below based mostly on sphinx.roles.XRefRole; run() and + # create_xref_node() + options =3D { + "refdoc": env.docname, + "refdomain": domain, + "reftype": rolename, + "refexplicit": False, + "refwarn": role.warn_dangling, + } + refnode =3D role.nodeclass(target, **options) + title, target =3D role.process_link(env, refnode, False, target, targe= t) + refnode["reftarget"] =3D target + classes =3D ["xref", domain, f"{domain}-{rolename}"] + refnode +=3D role.innernodeclass(target, title, classes=3Dclasses) + + # This is the very gross part of the hack. Normally, + # result_nodes takes a document object to which we would pass + # self.inliner.document. Prior to Sphinx 4.1, we don't *have* an + # inliner to pass, so we have nothing to pass here. However, the + # actual implementation of role.result_nodes in this case + # doesn't actually use that argument, so this winds up being + # ... fine. Rest easy at night knowing this code only runs under + # old versions of Sphinx, so at least it won't change in the + # future on us and lead to surprising new failures. + # Gross, I know. + result_nodes, _messages =3D role.result_nodes( + None, # type: ignore + env, + refnode, + is_ref=3DTrue, + ) + return nodes.inline(target, "", *result_nodes) + + +class CompatField(docfields.Field): + if MAKE_XREF_WORKAROUND: + make_xref =3D _compat_make_xref + + +class CompatGroupedField(docfields.GroupedField): + if MAKE_XREF_WORKAROUND: + make_xref =3D _compat_make_xref + + +class CompatTypedField(docfields.TypedField): + if MAKE_XREF_WORKAROUND: + make_xref =3D _compat_make_xref diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 753e07024f5..d3487c5dfeb 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -26,7 +26,14 @@ from docutils import nodes from docutils.parsers.rst import directives =20 -from compat import KeywordNode, SpaceNode, nested_parse +from compat import ( + CompatField, + CompatGroupedField, + CompatTypedField, + KeywordNode, + SpaceNode, + nested_parse, +) from sphinx import addnodes from sphinx.addnodes import desc_signature, pending_xref from sphinx.directives import ObjectDescription @@ -39,7 +46,6 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging -from sphinx.util.docfields import Field, GroupedField, TypedField from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode =20 @@ -187,7 +193,7 @@ class QAPIObject(ObjectDescription[Signature]): =20 doc_field_types =3D [ # :feat name: descr - GroupedField( + CompatGroupedField( "feature", label=3D_("Features"), names=3D("feat",), @@ -444,7 +450,7 @@ class QAPICommand(QAPIObject): doc_field_types.extend( [ # :arg TypeName ArgName: descr - TypedField( + CompatTypedField( "argument", label=3D_("Arguments"), names=3D("arg",), @@ -452,14 +458,14 @@ class QAPICommand(QAPIObject): can_collapse=3DFalse, ), # :error: descr - Field( + CompatField( "error", label=3D_("Errors"), names=3D("error", "errors"), has_arg=3DFalse, ), # :returns TypeName: descr - GroupedField( + CompatGroupedField( "returnvalue", label=3D_("Returns"), rolename=3D"type", @@ -477,7 +483,7 @@ class QAPIEnum(QAPIObject): doc_field_types.extend( [ # :value name: descr - GroupedField( + CompatGroupedField( "value", label=3D_("Values"), names=3D("value",), @@ -494,7 +500,7 @@ class QAPIAlternate(QAPIObject): doc_field_types.extend( [ # :choice type name: descr - TypedField( + CompatTypedField( "choice", label=3D_("Choices"), names=3D("choice",), @@ -512,7 +518,7 @@ class QAPIObjectWithMembers(QAPIObject): doc_field_types.extend( [ # :member type name: descr - TypedField( + CompatTypedField( "member", label=3D_("Members"), names=3D("memb",), --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146533; cv=none; d=zohomail.com; s=zohoarc; b=lSFi4DqpmBYYpvZDeN/BYwI/+U+Uvwx66gh5iw71JZrK4xyMmEXF3FULsVAeLi01FyuxqRkn0JkDcLSXg4zSw+3f4BDQts3uz+RCt7M2xO54i8KpK+5DhiGV7jdxJ8FX/ZQh/HMBFSNk0ryDFT4nXjQm2i1K8NvnC1bqN9YQkTg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146533; 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=SEbRJu3P2GEL4Q0RJzrGJnkCauZsla3j3eqH9AIiSI8=; b=MhetQm3yFsxVP4jDRPYGYPxMnBfkWErVh/eQwqHieBBf78DRogd5cBwFpg1cPwcSBom89EuDO4s9xUb7iGptxR6tu9ndD6z+Eln0Aqn83jpgnaT1BV/g6jkBA/J+LOKNinuM2ew+kIc6QhccwdZzlW3v2/jCAB3NaeggG2hwk+c= 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 1741146533455963.144175421791; Tue, 4 Mar 2025 19:48:53 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk4-0001Ce-Is; Tue, 04 Mar 2025 22:48:20 -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 1tpfk0-0000qE-6M for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:16 -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 1tpfjy-0006GG-Rq for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:15 -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-554-irpkm4ZYOaKUrsqWWWEWSQ-1; Tue, 04 Mar 2025 22:48:01 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 CFC4F19039DF; Wed, 5 Mar 2025 03:47:59 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 35F261956095; Wed, 5 Mar 2025 03:47:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146494; 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=SEbRJu3P2GEL4Q0RJzrGJnkCauZsla3j3eqH9AIiSI8=; b=DL1Dp8Ql9GwDyZVFXEaC0Bf8h9GL7zfsTqDS24qiN+WJS7lXtS+xZAVPxY4v2r2ngWneuh aenic/BBoTwekUz11NyNvsad4Swg7kkE9QewHAZiHd0jBpKXPJlPLpwwlksdjacIfH+/nn GfuBWttJ0pMdzgll9t/I7CgEPOktjLY= X-MC-Unique: irpkm4ZYOaKUrsqWWWEWSQ-1 X-Mimecast-MFC-AGG-ID: irpkm4ZYOaKUrsqWWWEWSQ_1741146479 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 28/57] docs/qapi-domain: warn when QAPI domain xrefs fail to resolve Date: Tue, 4 Mar 2025 22:45:37 -0500 Message-ID: <20250305034610.960147-29-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146536761019100 Content-Type: text/plain; charset="utf-8" This patch adds a warning (which is a build failure under our current build settings) whenever a QAPI cross-reference fails to resolve. This applies to any cross-references of the form :qapi:{role}:`foo`, which covers all of the automatically generated references by the qapi domain, and any such references that are manually written into the documentation rst files. Cross-references of the form `foo` do not use this system, but are already configured to issue a warning (Again, a build failure) if the cross-reference isn't found anywhere. Adds warnings that look like the following: docs/qapi/index.rst:48: WARNING: qapi:type reference target not found: 'foo= type' [ref.qapi] docs/qapi/index.rst:50: WARNING: qapi:mod reference target not found: 'foom= od' [ref.qapi] Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d3487c5dfeb..9a11a2dcbe0 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -882,6 +882,29 @@ def resolve_xref( matches =3D self.find_obj(modname, target, typ) =20 if not matches: + # Normally, we could pass warn_dangling=3DTrue to QAPIXRefRole= (), + # but that will trigger on references to these built-in types, + # which we'd like to ignore instead. + + # Take care of that warning here instead, so long as the + # reference isn't to one of our built-in core types. + if target not in ( + "string", + "number", + "int", + "boolean", + "null", + "value", + "q_empty", + ): + logger.warning( + __("qapi:%s reference target not found: %r"), + typ, + target, + type=3D"ref", + subtype=3D"qapi", + location=3Dnode, + ) return None =20 if len(matches) > 1: --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146523; cv=none; d=zohomail.com; s=zohoarc; b=iaUUHuk96IuzOn+7qYPa233ci/kbRpzB7KacQuuVdNYDUZwcJMOds8gltXsnXz8gFkRv+L6+SpcPGpU2HNc10LLg9iL/GRoGRFy8uq5Yat6RME5Ps0sJp2kWxpwerVjKsLYQEDqxe6FXKoWMNhnKQta0zvUoenqLTqi3LYJzJ4Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146523; 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=Xjrvi7N8n46beIgRb552NDK9zm0wuktcVMLvc+e5dro=; b=LjQ+P4MabJm9DrZZcWv4ONic6tQ2GCYPjqLqmAULSF2N4LNXaXblSeh1/F+oj+bftodGVX48Ax7Bv7MVleFOQQNl4kDgtXHEuL5ZWBwyHWkUOAB/e8eFjrhGuu9bYzJd9GhP+JZ/lnLGoFMIgz/RM7turJ/cUvFGhlPmMRpXJbE= 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 1741146523703209.2943833342058; Tue, 4 Mar 2025 19:48:43 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk9-0001jK-8D; Tue, 04 Mar 2025 22:48: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 1tpfk2-000155-Cq for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:18 -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 1tpfk0-0006Gb-Mm for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:18 -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-576-ULkdddoRMqKsd_Yxaf1IpA-1; Tue, 04 Mar 2025 22:48:04 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 78C841801A05; Wed, 5 Mar 2025 03:48:03 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 22B0F1955DDE; Wed, 5 Mar 2025 03:47:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146495; 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=Xjrvi7N8n46beIgRb552NDK9zm0wuktcVMLvc+e5dro=; b=JXqLXe2RaSpKgp3g3SW4mWabRRLn2JjYAalp/iJapD3pWO0swkEyigd4fgVLfqR9hwFhYD jz3J/b0mcmAr0LPan+wP9200Ahc32H/PUMN0j0h903BGAQZK04vm9lixmKlqgaNdhDnfLf lH1UvALyZsbpSOY1Q3MGDohuU6H2VcA= X-MC-Unique: ULkdddoRMqKsd_Yxaf1IpA-1 X-Mimecast-MFC-AGG-ID: ULkdddoRMqKsd_Yxaf1IpA_1741146483 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 29/57] docs/qapi-domain: Fix error context reporting in Sphinx 5.x and 6.x Date: Tue, 4 Mar 2025 22:45:38 -0500 Message-ID: <20250305034610.960147-30-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146526965019100 Content-Type: text/plain; charset="utf-8" Sphinx 5.3.0 to Sphinx 6.2.0 has a bug where nested content in an ObjectDescription content block has its error position reported incorrectly due to an oversight when they added nested section support to this directive. (This bug is present in Sphinx's own Python and C domains; test it yourself by creating a py:func directive and creating a syntax error in the directive's content block. The reporting will be incorrect.) To avoid overriding and re-implementing the entirety of the run() method, a workaround is employed where we parse the content block ourselves in before_content(), then null the content block to make Sphinx's own parsing a no-op. Then, in transform_content (which occurs after Sphinx's nested parse), we simply swap our own parsed content tree back in for Sphinx's. It appears a little tricky, but it's the nicest solution I can find. Signed-off-by: John Snow --- docs/sphinx/compat.py | 56 ++++++++++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 13 +++++---- 2 files changed, 63 insertions(+), 6 deletions(-) diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py index 7e8d72c9b1f..e13bee5c209 100644 --- a/docs/sphinx/compat.py +++ b/docs/sphinx/compat.py @@ -4,6 +4,7 @@ =20 import re from typing import ( + TYPE_CHECKING, Any, Callable, Optional, @@ -12,9 +13,11 @@ =20 from docutils import nodes from docutils.nodes import Element, Node, Text +from docutils.statemachine import StringList =20 import sphinx from sphinx import addnodes +from sphinx.directives import ObjectDescription from sphinx.environment import BuildEnvironment from sphinx.roles import XRefRole from sphinx.util import docfields @@ -171,3 +174,56 @@ class CompatGroupedField(docfields.GroupedField): class CompatTypedField(docfields.TypedField): if MAKE_XREF_WORKAROUND: make_xref =3D _compat_make_xref + + +# ################################################################ +# Nested parsing error location fix for Sphinx 5.3.0 < x < 6.2.0 # +# ################################################################ + +# When we require Sphinx 4.x, the TYPE_CHECKING hack where we avoid +# subscripting ObjectDescription at runtime can be removed in favor of +# just always subscripting the class. + +# When we require Sphinx > 6.2.0, the rest of this compatibility hack +# can be dropped and QAPIObject can just inherit directly from +# ObjectDescription[Signature]. + +SOURCE_LOCATION_FIX =3D (5, 3, 0) <=3D sphinx.version_info[:3] < (6, 2, 0) + +Signature =3D str + + +if TYPE_CHECKING: + _BaseClass =3D ObjectDescription[Signature] +else: + _BaseClass =3D ObjectDescription + + +class ParserFix(_BaseClass): + + _temp_content: StringList + _temp_offset: int + _temp_node: Optional[addnodes.desc_content] + + def before_content(self) -> None: + # Work around a sphinx bug and parse the content ourselves. + self._temp_content =3D self.content + self._temp_offset =3D self.content_offset + self._temp_node =3D None + + if SOURCE_LOCATION_FIX: + self._temp_node =3D addnodes.desc_content() + self.state.nested_parse( + self.content, self.content_offset, self._temp_node + ) + # Sphinx will try to parse the content block itself, + # Give it nothingness to parse instead. + self.content =3D StringList() + self.content_offset =3D 0 + + def transform_content(self, content_node: addnodes.desc_content) -> No= ne: + # Sphinx workaround: Inject our parsed content and restore state. + if self._temp_node: + content_node +=3D self._temp_node.children + self.content =3D self._temp_content + self.content_offset =3D self._temp_offset diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 9a11a2dcbe0..077ab7ae47a 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -31,6 +31,8 @@ CompatGroupedField, CompatTypedField, KeywordNode, + ParserFix, + Signature, SpaceNode, nested_parse, ) @@ -163,12 +165,7 @@ def since_validator(param: str) -> str: return param =20 =20 -# Alias for the return of handle_signature(), which is used in several pla= ces. -# (In the Python domain, this is Tuple[str, str] instead.) -Signature =3D str - - -class QAPIObject(ObjectDescription[Signature]): +class QAPIObject(ParserFix): """ Description of a generic QAPI object. =20 @@ -415,6 +412,10 @@ def _validate_field(self, field: nodes.field) -> None: logger.warning(msg, location=3Dfield) =20 def transform_content(self, content_node: addnodes.desc_content) -> No= ne: + # This hook runs after before_content and the nested parse, but + # before the DocFieldTransformer is executed. + super().transform_content(content_node) + self._add_infopips(content_node) =20 # Validate field lists. --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146541; cv=none; d=zohomail.com; s=zohoarc; b=ktvN5pJIj+2LpgsFCmJop3t8qFqWqXRb89aM1BoZrbci8ElrFNJx2mY3Cm5UtCoDmDkyU7iOqprW5ZPyBnRDNf+gRR//YUlGD+kBtdsefkarNntTjA+1udPUu6Ocg71BO6QeL5S90UWhOvCLSPeS7QxdIh98rkjTEdtZ0zM9klo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146541; 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=Fj6TyXCNkS7nB15MA0gUAfhjROX2FPBPlpiCQPNzP6HPTw+4KK0j8r1pKg9vqZOLbeKcYVKaWAYgkTey1WWSSYptSTzggZEZqhY5dknVGLtXBsk3IaZQODS8JKM5oBw84C8NZYJ5ff+h9J1bMgSizDDsDywgwim3GKl9I43nse0= 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 1741146541731956.3856885436361; Tue, 4 Mar 2025 19:49:01 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk9-0001mz-UO; Tue, 04 Mar 2025 22:48: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 1tpfk7-0001VZ-8z for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:23 -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 1tpfk5-0006Hn-K3 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:22 -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-160-yTjHx0GcMzyk_foYAthDZQ-1; Tue, 04 Mar 2025 22:48:08 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 E213B1800258; Wed, 5 Mar 2025 03:48:06 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1FC411956095; Wed, 5 Mar 2025 03:48:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146501; 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=e2fRAJuAtIE3URvgHOGS6kqj8WiJD0FGGEwVTKv30afCD0j4RIvwfGH5S3Kh2zQ7yPZFOe TXbzpAePmH+QADVUqAVtJrOX+hHTTzNqqYCDjKxL3OXCwJVxNM+U6TbZGqqYt6ukt3jfQt oBhnnhaR11PW2hfPb8HH0LhbWE0AruE= X-MC-Unique: yTjHx0GcMzyk_foYAthDZQ-1 X-Mimecast-MFC-AGG-ID: yTjHx0GcMzyk_foYAthDZQ_1741146487 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 30/57] qapi/parser: adjust info location for doc body section Date: Tue, 4 Mar 2025 22:45:39 -0500 Message-ID: <20250305034610.960147-31-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146543228019000 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 --- 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 Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146653; cv=none; d=zohomail.com; s=zohoarc; b=HBxu+9mPrgFfQ6h7Q6XcxZzjziXRHrc7s9AHHqzkbp1vy/CJnNCPtwLyATwqPYsU76v7ATYf/nUxvJRK3rW2aA9vwzTeXPAMcJjuWVbuLSEwxKuuFXBMRhknIu7EUJZP1ynC4hvn7kNkaBDO/wSBw5lhg0OruLWQQur0/hJDkiU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146653; 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=r1JNi4CCkHGnqyEe1cKrsulrxnUCy5RqhRkiSMKGUC0=; b=MM7sKHF8ADfFWiDo/93NYv5NsgARvlFcuHQtp1iF0HMfDO8Lj12KmEeOS9ydbvxnbFDn7yiZ7Hn0TIDR6oD89WdDOGr+4YzR6MJ+OSsXvX2wkg6rGrP4EqEIb5NSuHxQSrGzrDU7LrQDT5YxPn16nbX4NqgoHJzeH7ZiSXSFwWk= 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 1741146653076390.3029987208746; Tue, 4 Mar 2025 19:50:53 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfk6-0001Pp-PK; Tue, 04 Mar 2025 22:48:22 -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 1tpfjz-0000oq-OG for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:16 -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 1tpfjx-0006Fv-KV for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:15 -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-88-1dE-jdiLMWaEwNKGWya4Cw-1; Tue, 04 Mar 2025 22:48:11 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 69408180AF57; Wed, 5 Mar 2025 03:48:10 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3552C1956095; Wed, 5 Mar 2025 03:48:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146493; 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=r1JNi4CCkHGnqyEe1cKrsulrxnUCy5RqhRkiSMKGUC0=; b=KGBUTDpAfo69LjxRlBwgb+qdUyOVwoyKhXOZY/R5sCJWz/DHK/YMCiKWYOG3bmZeGMT49j 87woB6E3jIrJ6G8zigFzHGYuLu+HB11ft6P7tWvedX6ZUKfFItG/aUuaSKh4yCjvo9gHVy 0gDewP2OgS0Hn8NuJKxmy+1LQfgOijk= X-MC-Unique: 1dE-jdiLMWaEwNKGWya4Cw-1 X-Mimecast-MFC-AGG-ID: 1dE-jdiLMWaEwNKGWya4Cw_1741146490 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 31/57] qapi: expand tags to all doc sections Date: Tue, 4 Mar 2025 22:45:40 -0500 Message-ID: <20250305034610.960147-32-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146655167019100 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 --- 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 0a9da3efdeb..5773f1dd6d6 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -113,7 +113,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 @@ -171,15 +171,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 @@ -212,7 +212,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 Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146596; cv=none; d=zohomail.com; s=zohoarc; b=mnvMVVSvmReG62GgZAQjrvAoKUV3LinNBBRUr5VHt/NFmjlHVJ3JG2xczrwrYXjzt8+uHGgQMJJqiqrBB9z7mkjbZlTI0zzaEdnxSXy9CubGWNb5akkXpWZEO7SPw+vJRaP1nPRiljZ23x2w6Azpe1G9jvcuTGUHQZREi3iME1Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146596; 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=aFq1qUit74Gp3X8TERcLqBPvPfo0Qw+YAyoZvTecjXU3ohol+oHLSPJ5EvAhcGOmhkqxXVMuKNRqJZtfvVxtWODwOtsCZB554aPh0LatBLkFAB/FncWSrHn3xVqctAX6p4k0v+2Z55hUc5o66Abw7yhsfUZMc4/TvQIdsJnQ5ic= 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 174114659674958.260577770360214; Tue, 4 Mar 2025 19:49:56 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkB-0001th-6W; Tue, 04 Mar 2025 22:48: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 1tpfk3-00019H-L0 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:19 -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 1tpfk1-0006Gq-G9 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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-479-ePnOzsiAMCWWqR0AEyW0PA-1; Tue, 04 Mar 2025 22:48:15 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 46E75180AF60; Wed, 5 Mar 2025 03:48:14 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B665E1956095; Wed, 5 Mar 2025 03:48:10 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146496; 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=h9+Gz+afVoIjkNB3Fp0e6IQ1WrfTgAMXWNABjPtBMkX/QifUWKMlBkxQET7hg5knTnHOVn 8q6WxvV3c4WEISIRjljU+ToW2Pak4X20GYIgHK1s33tqoI+zRjxIRSaogGckr+/4L/Pmh4 WI0w7vscZAIJK6ZuOEft+UIGg+EBtnE= X-MC-Unique: ePnOzsiAMCWWqR0AEyW0PA-1 X-Mimecast-MFC-AGG-ID: ePnOzsiAMCWWqR0AEyW0PA_1741146494 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 32/57] qapi/schema: add __repr__ to QAPIDoc.Section Date: Tue, 4 Mar 2025 22:45:41 -0500 Message-ID: <20250305034610.960147-33-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146598855019100 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 --- 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 Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146551; cv=none; d=zohomail.com; s=zohoarc; b=gXysgkaE6LWD/zrZ3Il8/2OspWweo0lg5IUivtaud0rcWPPC1VIxBEe+EalvLxhfojr30qBX0dowFRmAM6FVYM+LpBCYd+Pow01SKCk6Yel4U9ohDcM7wmFibOmvj6lnPmKzQuFG7/prcGNT0UVye7HGHvNAE36r1G43ePo41l8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146551; 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=eadiWBlR8Z+CsMYhX8s/SxKboBGtl9dr70e/tCmPGZIaSpSrbBQVuu8usUxAqSifSSXrtRqg3KVBTPxQ8tk4KSlUhoMGkIgm211cadU/OFK8wBL+msOgJ+DykP+JOA4VBGmEpq8UwfVO23aCpQNu5e/bygjC8vvpX7djeFV6Kmk= 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 174114655124556.115545583060566; Tue, 4 Mar 2025 19:49:11 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkC-00023K-Uf; Tue, 04 Mar 2025 22:48: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 1tpfk8-0001hr-UN for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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 1tpfk7-0006I6-5Y for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:24 -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-54-IW5jUfzwP0SmPAUhzdE2XA-1; Tue, 04 Mar 2025 22:48:18 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 5A14C1955BCD; Wed, 5 Mar 2025 03:48:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D7F801956095; Wed, 5 Mar 2025 03:48:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146502; 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=NbQPZXVCwSeUNY732E261haFp2neItMrtbyQdVZBTKYr7u2K0D8qCxpaAH06IhbrdSWrkf namJ2RLybE813jhgpu2lfvi5UWqS2KkMfsoWhAiI1yNAkNiJAclVMgE3e5EFYmCzDerhpq N7wiIVGKXfQ78rUhxhICBh8oUkSYDLI= X-MC-Unique: IW5jUfzwP0SmPAUhzdE2XA-1 X-Mimecast-MFC-AGG-ID: IW5jUfzwP0SmPAUhzdE2XA_1741146497 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 33/57] docs/qapidoc: add transmogrifier stub Date: Tue, 4 Mar 2025 22:45:42 -0500 Message-ID: <20250305034610.960147-34-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146552790019100 Content-Type: text/plain; charset="utf-8" This commit adds a stubbed option to the qapi-doc directive that opts-in to the new rST generator; the implementation of which will follow in subsequent commits. Once all QAPI documents have been converted, this option and the old qapidoc implementation can be dropped. Note that moving code outside of the try...except block has no impact because the code moved outside of that block does not ever raise a QAPIError. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d622398f1da..dc72f3fd3f3 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -452,9 +452,9 @@ def _parse_text_into_node(self, doctext, node): rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.li= ne) self._sphinx_directive.do_parse(rstlist, node) =20 - def get_document_nodes(self): - """Return the list of docutils nodes which make up the document""" - return self._top_node.children + def get_document_node(self): + """Return the root docutils node which makes up the document""" + return self._top_node =20 =20 # Turn the black formatter on for the rest of the file. @@ -503,7 +503,10 @@ class QAPIDocDirective(NestedDirective): =20 required_argument =3D 1 optional_arguments =3D 1 - option_spec =3D {"qapifile": directives.unchanged_required} + option_spec =3D { + "qapifile": directives.unchanged_required, + "transmogrify": directives.flag, + } has_content =3D False =20 def new_serialno(self): @@ -511,10 +514,24 @@ def new_serialno(self): env =3D self.state.document.settings.env return "qapidoc-%d" % env.new_serialno("qapidoc") =20 + def transmogrify(self, schema) -> nodes.Element: + raise NotImplementedError + + def legacy(self, schema) -> nodes.Element: + vis =3D QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + return vis.get_document_node() + def run(self): env =3D self.state.document.settings.env qapifile =3D env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir =3D os.path.dirname(qapifile) + transmogrify =3D "transmogrify" in self.options =20 try: schema =3D QAPISchema(qapifile) @@ -522,20 +539,18 @@ def run(self): # First tell Sphinx about all the schema files that the # output documentation depends on (including 'qapifile' itself) schema.visit(QAPISchemaGenDepVisitor(env, qapidir)) - - vis =3D QAPISchemaGenRSTVisitor(self) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - return vis.get_document_nodes() except QAPIError as err: # Launder QAPI parse errors into Sphinx extension errors # so they are displayed nicely to the user raise ExtensionError(str(err)) from err =20 + if transmogrify: + contentnode =3D self.transmogrify(schema) + else: + contentnode =3D self.legacy(schema) + + return contentnode.children + =20 class QMPExample(CodeBlock, NestedDirective): """ --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146803; cv=none; d=zohomail.com; s=zohoarc; b=fl0Lv5v71nASbgU8E1ym77CA1g0rue9tPhviDwx6zJws1agcN+61Ro3z+7zRhfE+JGzmue820Kok5zfHxlIc50oSHUh/jzXT580Gf5nGL+PXjFenZjsP57CFR4nSpeYgjeHHCjcEHzsR+5vGRn/rwLYcMAedBPv13Iha0S3kOGg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146803; 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=FQtB7BFRPrUrui3CwN5LCMlUMM8qZncWQUjogGxRQEw=; b=lfXZ/QogHPP1pvUHOqKxAP2E0TOjhKZxYBm7iNLICH+CIFkenoKKMa1ce1xkuJMLCf2GDD2H6jakIqSMpOTuAmxItyxFfOGvqIa3Ag8owUo91/zpJAU9r8jcQXpQ25fdCKrJg5u/a2tqVasgQgpOse+QJurwbKsBKr+CIOWLu/4= 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 1741146803768749.4931555978782; Tue, 4 Mar 2025 19:53:23 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkW-0002av-GI; Tue, 04 Mar 2025 22:48:50 -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 1tpfkF-0002LK-A2 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:34 -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 1tpfkA-0006Iq-QY for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:30 -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-369-nuo_8wv3P5-pZ-3sDx9sSg-1; Tue, 04 Mar 2025 22:48:22 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 C58091955BC6; Wed, 5 Mar 2025 03:48:21 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E97D81956095; Wed, 5 Mar 2025 03:48:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146506; 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=FQtB7BFRPrUrui3CwN5LCMlUMM8qZncWQUjogGxRQEw=; b=SXJEK78P554TljjxzPcEykfoCB3ODgSHbqbIEDGppC6NOAVnqwwAmV6kCHTRvU0kDYXjze E4rEtpP0kMQFq0kriEMH7TBKtTzrVfs0sxvdI3dJRkNgMmTeM6NYrjqrT6DM/pjyY4BLH6 IiFkkxhZJ9K9CaSEQ5ClHoDRwocbA0g= X-MC-Unique: nuo_8wv3P5-pZ-3sDx9sSg-1 X-Mimecast-MFC-AGG-ID: nuo_8wv3P5-pZ-3sDx9sSg_1741146501 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 34/57] docs/qapidoc: split old implementation into qapidoc_legacy.py Date: Tue, 4 Mar 2025 22:45:43 -0500 Message-ID: <20250305034610.960147-35-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146806127019000 Content-Type: text/plain; charset="utf-8" This is being done primarily to be able to type check and delint the new implementation without needing to worry about fixing up the old implementation. I'm adding the new implementation into the existing file instead of into a new file so that when the dust settles, qapidoc.py will contain the full history of development on this generative module. This patch *should* be pure motion, give or take the import statements. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 420 +------------------------------- docs/sphinx/qapidoc_legacy.py | 439 ++++++++++++++++++++++++++++++++++ 2 files changed, 441 insertions(+), 418 deletions(-) create mode 100644 docs/sphinx/qapidoc_legacy.py diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index dc72f3fd3f3..f4abf42e7bf 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -25,19 +25,16 @@ """ =20 import os -import re import sys -import textwrap from typing import List =20 from docutils import nodes from docutils.parsers.rst import Directive, directives -from docutils.statemachine import ViewList -from qapi.error import QAPIError, QAPISemError +from qapi.error import QAPIError from qapi.gen import QAPISchemaVisitor -from qapi.parser import QAPIDoc from qapi.schema import QAPISchema =20 +from qapidoc_legacy import QAPISchemaGenRSTVisitor from sphinx import addnodes from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError @@ -48,419 +45,6 @@ __version__ =3D "1.0" =20 =20 -def dedent(text: str) -> str: - # Adjust indentation to make description text parse as paragraph. - - lines =3D text.splitlines(True) - if re.match(r"\s+", lines[0]): - # First line is indented; description started on the line after - # the name. dedent the whole block. - return textwrap.dedent(text) - - # Descr started on same line. Dedent line 2+. - return lines[0] + textwrap.dedent("".join(lines[1:])) - - -# Disable black auto-formatter until re-enabled: -# fmt: off - - -class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): - """A QAPI schema visitor which generates docutils/Sphinx nodes - - This class builds up a tree of docutils/Sphinx nodes corresponding - to documentation for the various QAPI objects. To use it, first - create a QAPISchemaGenRSTVisitor object, and call its - visit_begin() method. Then you can call one of the two methods - 'freeform' (to add documentation for a freeform documentation - chunk) or 'symbol' (to add documentation for a QAPI symbol). These - will cause the visitor to build up the tree of document - nodes. Once you've added all the documentation via 'freeform' and - 'symbol' method calls, you can call 'get_document_nodes' to get - the final list of document nodes (in a form suitable for returning - from a Sphinx directive's 'run' method). - """ - def __init__(self, sphinx_directive): - self._cur_doc =3D None - self._sphinx_directive =3D sphinx_directive - self._top_node =3D nodes.section() - self._active_headings =3D [self._top_node] - - def _make_dlitem(self, term, defn): - """Return a dlitem node with the specified term and definition. - - term should be a list of Text and literal nodes. - defn should be one of: - - a string, which will be handed to _parse_text_into_node - - a list of Text and literal nodes, which will be put into - a paragraph node - """ - dlitem =3D nodes.definition_list_item() - dlterm =3D nodes.term('', '', *term) - dlitem +=3D dlterm - if defn: - dldef =3D nodes.definition() - if isinstance(defn, list): - dldef +=3D nodes.paragraph('', '', *defn) - else: - self._parse_text_into_node(defn, dldef) - dlitem +=3D dldef - return dlitem - - def _make_section(self, title): - """Return a section node with optional title""" - section =3D nodes.section(ids=3D[self._sphinx_directive.new_serial= no()]) - if title: - section +=3D nodes.title(title, title) - return section - - def _nodes_for_ifcond(self, ifcond, with_if=3DTrue): - """Return list of Text, literal nodes for the ifcond - - Return a list which gives text like ' (If: condition)'. - If with_if is False, we don't return the "(If: " and ")". - """ - - doc =3D ifcond.docgen() - if not doc: - return [] - doc =3D nodes.literal('', doc) - if not with_if: - return [doc] - - nodelist =3D [nodes.Text(' ('), nodes.strong('', 'If: ')] - nodelist.append(doc) - nodelist.append(nodes.Text(')')) - return nodelist - - def _nodes_for_one_member(self, member): - """Return list of Text, literal nodes for this member - - Return a list of doctree nodes which give text like - 'name: type (optional) (If: ...)' suitable for use as the - 'term' part of a definition list item. - """ - term =3D [nodes.literal('', member.name)] - if member.type.doc_type(): - term.append(nodes.Text(': ')) - term.append(nodes.literal('', member.type.doc_type())) - if member.optional: - term.append(nodes.Text(' (optional)')) - if member.ifcond.is_present(): - term.extend(self._nodes_for_ifcond(member.ifcond)) - return term - - def _nodes_for_variant_when(self, branches, variant): - """Return list of Text, literal nodes for variant 'when' clause - - Return a list of doctree nodes which give text like - 'when tagname is variant (If: ...)' suitable for use in - the 'branches' part of a definition list. - """ - term =3D [nodes.Text(' when '), - nodes.literal('', branches.tag_member.name), - nodes.Text(' is '), - nodes.literal('', '"%s"' % variant.name)] - if variant.ifcond.is_present(): - term.extend(self._nodes_for_ifcond(variant.ifcond)) - return term - - def _nodes_for_members(self, doc, what, base=3DNone, branches=3DNone): - """Return list of doctree nodes for the table of members""" - dlnode =3D nodes.definition_list() - for section in doc.args.values(): - term =3D self._nodes_for_one_member(section.member) - # TODO drop fallbacks when undocumented members are outlawed - if section.text: - defn =3D dedent(section.text) - else: - defn =3D [nodes.Text('Not documented')] - - dlnode +=3D self._make_dlitem(term, defn) - - if base: - dlnode +=3D self._make_dlitem([nodes.Text('The members of '), - nodes.literal('', base.doc_type()= )], - None) - - if branches: - for v in branches.variants: - if v.type.name =3D=3D 'q_empty': - continue - assert not v.type.is_implicit() - term =3D [nodes.Text('The members of '), - nodes.literal('', v.type.doc_type())] - term.extend(self._nodes_for_variant_when(branches, v)) - dlnode +=3D self._make_dlitem(term, None) - - if not dlnode.children: - return [] - - section =3D self._make_section(what) - section +=3D dlnode - return [section] - - def _nodes_for_enum_values(self, doc): - """Return list of doctree nodes for the table of enum values""" - seen_item =3D False - dlnode =3D nodes.definition_list() - for section in doc.args.values(): - termtext =3D [nodes.literal('', section.member.name)] - if section.member.ifcond.is_present(): - termtext.extend(self._nodes_for_ifcond(section.member.ifco= nd)) - # TODO drop fallbacks when undocumented members are outlawed - if section.text: - defn =3D dedent(section.text) - else: - defn =3D [nodes.Text('Not documented')] - - dlnode +=3D self._make_dlitem(termtext, defn) - seen_item =3D True - - if not seen_item: - return [] - - section =3D self._make_section('Values') - section +=3D dlnode - return [section] - - def _nodes_for_arguments(self, doc, arg_type): - """Return list of doctree nodes for the arguments section""" - if arg_type and not arg_type.is_implicit(): - assert not doc.args - section =3D self._make_section('Arguments') - dlnode =3D nodes.definition_list() - dlnode +=3D self._make_dlitem( - [nodes.Text('The members of '), - nodes.literal('', arg_type.name)], - None) - section +=3D dlnode - return [section] - - return self._nodes_for_members(doc, 'Arguments') - - def _nodes_for_features(self, doc): - """Return list of doctree nodes for the table of features""" - seen_item =3D False - dlnode =3D nodes.definition_list() - for section in doc.features.values(): - dlnode +=3D self._make_dlitem( - [nodes.literal('', section.member.name)], dedent(section.t= ext)) - seen_item =3D True - - if not seen_item: - return [] - - section =3D self._make_section('Features') - section +=3D dlnode - return [section] - - def _nodes_for_sections(self, doc): - """Return list of doctree nodes for additional sections""" - nodelist =3D [] - for section in doc.sections: - if section.kind =3D=3D QAPIDoc.Kind.TODO: - # Hide TODO: sections - continue - - 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() - self._parse_text_into_node(section.text, container) - nodelist +=3D container.children - continue - - snode =3D self._make_section(section.kind.name.title()) - self._parse_text_into_node(dedent(section.text), snode) - nodelist.append(snode) - return nodelist - - def _nodes_for_if_section(self, ifcond): - """Return list of doctree nodes for the "If" section""" - nodelist =3D [] - if ifcond.is_present(): - snode =3D self._make_section('If') - snode +=3D nodes.paragraph( - '', '', *self._nodes_for_ifcond(ifcond, with_if=3DFalse) - ) - nodelist.append(snode) - return nodelist - - def _add_doc(self, typ, sections): - """Add documentation for a command/object/enum... - - We assume we're documenting the thing defined in self._cur_doc. - typ is the type of thing being added ("Command", "Object", etc) - - sections is a list of nodes for sections to add to the definition. - """ - - doc =3D self._cur_doc - snode =3D nodes.section(ids=3D[self._sphinx_directive.new_serialno= ()]) - snode +=3D nodes.title('', '', *[nodes.literal(doc.symbol, doc.sym= bol), - nodes.Text(' (' + typ + ')')]) - self._parse_text_into_node(doc.body.text, snode) - for s in sections: - if s is not None: - snode +=3D s - self._add_node_to_current_heading(snode) - - def visit_enum_type(self, name, info, ifcond, features, members, prefi= x): - doc =3D self._cur_doc - self._add_doc('Enum', - self._nodes_for_enum_values(doc) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_object_type(self, name, info, ifcond, features, - base, members, branches): - doc =3D self._cur_doc - if base and base.is_implicit(): - base =3D None - self._add_doc('Object', - self._nodes_for_members(doc, 'Members', base, branch= es) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_alternate_type(self, name, info, ifcond, features, - alternatives): - doc =3D self._cur_doc - self._add_doc('Alternate', - self._nodes_for_members(doc, 'Members') - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_command(self, name, info, ifcond, features, arg_type, - ret_type, gen, success_response, boxed, allow_oob, - allow_preconfig, coroutine): - doc =3D self._cur_doc - self._add_doc('Command', - self._nodes_for_arguments(doc, arg_type) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_event(self, name, info, ifcond, features, arg_type, boxed): - doc =3D self._cur_doc - self._add_doc('Event', - self._nodes_for_arguments(doc, arg_type) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def symbol(self, doc, entity): - """Add documentation for one symbol to the document tree - - This is the main entry point which causes us to add documentation - nodes for a symbol (which could be a 'command', 'object', 'event', - etc). We do this by calling 'visit' on the schema entity, which - will then call back into one of our visit_* methods, depending - on what kind of thing this symbol is. - """ - self._cur_doc =3D doc - entity.visit(self) - self._cur_doc =3D None - - def _start_new_heading(self, heading, level): - """Start a new heading at the specified heading level - - Create a new section whose title is 'heading' and which is placed - in the docutils node tree as a child of the most recent level-1 - heading. Subsequent document sections (commands, freeform doc chun= ks, - etc) will be placed as children of this new heading section. - """ - if len(self._active_headings) < level: - raise QAPISemError(self._cur_doc.info, - 'Level %d subheading found outside a ' - 'level %d heading' - % (level, level - 1)) - snode =3D self._make_section(heading) - self._active_headings[level - 1] +=3D snode - self._active_headings =3D self._active_headings[:level] - self._active_headings.append(snode) - return snode - - def _add_node_to_current_heading(self, node): - """Add the node to whatever the current active heading is""" - self._active_headings[-1] +=3D node - - def freeform(self, doc): - """Add a piece of 'freeform' documentation to the document tree - - A 'freeform' document chunk doesn't relate to any particular - symbol (for instance, it could be an introduction). - - If the freeform document starts with a line of the form - '=3D Heading text', this is a section or subsection heading, with - the heading level indicated by the number of '=3D' signs. - """ - - # QAPIDoc documentation says free-form documentation blocks - # must have only a body section, nothing else. - assert not doc.sections - assert not doc.args - assert not doc.features - self._cur_doc =3D doc - - text =3D doc.body.text - 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(' ') - node =3D self._start_new_heading(heading, len(leader)) - if text =3D=3D '': - return - else: - node =3D nodes.container() - - self._parse_text_into_node(text, node) - self._cur_doc =3D None - - def _parse_text_into_node(self, doctext, node): - """Parse a chunk of QAPI-doc-format text into the node - - The doc comment can contain most inline rST markup, including - bulleted and enumerated lists. - As an extra permitted piece of markup, @var will be turned - into ``var``. - """ - - # Handle the "@var means ``var`` case - doctext =3D re.sub(r'@([\w-]+)', r'``\1``', doctext) - - rstlist =3D ViewList() - for line in doctext.splitlines(): - # The reported line number will always be that of the start li= ne - # of the doc comment, rather than the actual location of the e= rror. - # Being more precise would require overhaul of the QAPIDoc cla= ss - # to track lines more exactly within all the sub-parts of the = doc - # comment, as well as counting lines here. - rstlist.append(line, self._cur_doc.info.fname, - self._cur_doc.info.line) - # Append a blank line -- in some cases rST syntax errors get - # attributed to the line after one with actual text, and if there - # isn't anything in the ViewList corresponding to that then Sphinx - # 1.6's AutodocReporter will then misidentify the source/line loca= tion - # in the error message (usually attributing it to the top-level - # .rst file rather than the offending .json file). The extra blank - # line won't affect the rendered output. - rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.li= ne) - self._sphinx_directive.do_parse(rstlist, node) - - def get_document_node(self): - """Return the root docutils node which makes up the document""" - return self._top_node - - -# Turn the black formatter on for the rest of the file. -# fmt: on - - class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module =20 diff --git a/docs/sphinx/qapidoc_legacy.py b/docs/sphinx/qapidoc_legacy.py new file mode 100644 index 00000000000..679f38356b1 --- /dev/null +++ b/docs/sphinx/qapidoc_legacy.py @@ -0,0 +1,439 @@ +# coding=3Dutf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. + +""" +qapidoc is a Sphinx extension that implements the qapi-doc directive + +The purpose of this extension is to read the documentation comments +in QAPI schema files, and insert them all into the current document. + +It implements one new rST directive, "qapi-doc::". +Each qapi-doc:: directive takes one argument, which is the +pathname of the schema file to process, relative to the source tree. + +The docs/conf.py file must set the qapidoc_srctree config value to +the root of the QEMU source tree. + +The Sphinx documentation on writing extensions is at: +https://www.sphinx-doc.org/en/master/development/index.html +""" + +import re +import textwrap + +from docutils import nodes +from docutils.statemachine import ViewList +from qapi.error import QAPISemError +from qapi.gen import QAPISchemaVisitor +from qapi.parser import QAPIDoc + + +def dedent(text: str) -> str: + # Adjust indentation to make description text parse as paragraph. + + lines =3D text.splitlines(True) + if re.match(r"\s+", lines[0]): + # First line is indented; description started on the line after + # the name. dedent the whole block. + return textwrap.dedent(text) + + # Descr started on same line. Dedent line 2+. + return lines[0] + textwrap.dedent("".join(lines[1:])) + + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first + create a QAPISchemaGenRSTVisitor object, and call its + visit_begin() method. Then you can call one of the two methods + 'freeform' (to add documentation for a freeform documentation + chunk) or 'symbol' (to add documentation for a QAPI symbol). These + will cause the visitor to build up the tree of document + nodes. Once you've added all the documentation via 'freeform' and + 'symbol' method calls, you can call 'get_document_nodes' to get + the final list of document nodes (in a form suitable for returning + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc =3D None + self._sphinx_directive =3D sphinx_directive + self._top_node =3D nodes.section() + self._active_headings =3D [self._top_node] + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem =3D nodes.definition_list_item() + dlterm =3D nodes.term('', '', *term) + dlitem +=3D dlterm + if defn: + dldef =3D nodes.definition() + if isinstance(defn, list): + dldef +=3D nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem +=3D dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section =3D nodes.section(ids=3D[self._sphinx_directive.new_serial= no()]) + if title: + section +=3D nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=3DTrue): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: condition)'. + If with_if is False, we don't return the "(If: " and ")". + """ + + doc =3D ifcond.docgen() + if not doc: + return [] + doc =3D nodes.literal('', doc) + if not with_if: + return [doc] + + nodelist =3D [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.append(doc) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term =3D [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond.is_present(): + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, branches, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'branches' part of a definition list. + """ + term =3D [nodes.Text(' when '), + nodes.literal('', branches.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond.is_present(): + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=3DNone, branches=3DNone): + """Return list of doctree nodes for the table of members""" + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + term =3D self._nodes_for_one_member(section.member) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D dedent(section.text) + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(term, defn) + + if base: + dlnode +=3D self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type()= )], + None) + + if branches: + for v in branches.variants: + if v.type.name =3D=3D 'q_empty': + continue + assert not v.type.is_implicit() + term =3D [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(branches, v)) + dlnode +=3D self._make_dlitem(term, None) + + if not dlnode.children: + return [] + + section =3D self._make_section(what) + section +=3D dlnode + return [section] + + def _nodes_for_enum_values(self, doc): + """Return list of doctree nodes for the table of enum values""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + termtext =3D [nodes.literal('', section.member.name)] + if section.member.ifcond.is_present(): + termtext.extend(self._nodes_for_ifcond(section.member.ifco= nd)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D dedent(section.text) + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(termtext, defn) + seen_item =3D True + + if not seen_item: + return [] + + section =3D self._make_section('Values') + section +=3D dlnode + return [section] + + def _nodes_for_arguments(self, doc, arg_type): + """Return list of doctree nodes for the arguments section""" + if arg_type and not arg_type.is_implicit(): + assert not doc.args + section =3D self._make_section('Arguments') + dlnode =3D nodes.definition_list() + dlnode +=3D self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', arg_type.name)], + None) + section +=3D dlnode + return [section] + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return list of doctree nodes for the table of features""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.features.values(): + dlnode +=3D self._make_dlitem( + [nodes.literal('', section.member.name)], dedent(section.t= ext)) + seen_item =3D True + + if not seen_item: + return [] + + section =3D self._make_section('Features') + section +=3D dlnode + return [section] + + def _nodes_for_sections(self, doc): + """Return list of doctree nodes for additional sections""" + nodelist =3D [] + for section in doc.sections: + if section.kind =3D=3D QAPIDoc.Kind.TODO: + # Hide TODO: sections + continue + + 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() + self._parse_text_into_node(section.text, container) + nodelist +=3D container.children + continue + + snode =3D self._make_section(section.kind.name.title()) + self._parse_text_into_node(dedent(section.text), snode) + nodelist.append(snode) + return nodelist + + def _nodes_for_if_section(self, ifcond): + """Return list of doctree nodes for the "If" section""" + nodelist =3D [] + if ifcond.is_present(): + snode =3D self._make_section('If') + snode +=3D nodes.paragraph( + '', '', *self._nodes_for_ifcond(ifcond, with_if=3DFalse) + ) + nodelist.append(snode) + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc =3D self._cur_doc + snode =3D nodes.section(ids=3D[self._sphinx_directive.new_serialno= ()]) + snode +=3D nodes.title('', '', *[nodes.literal(doc.symbol, doc.sym= bol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode +=3D s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, features, members, prefi= x): + doc =3D self._cur_doc + self._add_doc('Enum', + self._nodes_for_enum_values(doc) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_object_type(self, name, info, ifcond, features, + base, members, branches): + doc =3D self._cur_doc + if base and base.is_implicit(): + base =3D None + self._add_doc('Object', + self._nodes_for_members(doc, 'Members', base, branch= es) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_alternate_type(self, name, info, ifcond, features, + alternatives): + doc =3D self._cur_doc + self._add_doc('Alternate', + self._nodes_for_members(doc, 'Members') + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_command(self, name, info, ifcond, features, arg_type, + ret_type, gen, success_response, boxed, allow_oob, + allow_preconfig, coroutine): + doc =3D self._cur_doc + self._add_doc('Command', + self._nodes_for_arguments(doc, arg_type) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_event(self, name, info, ifcond, features, arg_type, boxed): + doc =3D self._cur_doc + self._add_doc('Event', + self._nodes_for_arguments(doc, arg_type) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc =3D doc + entity.visit(self) + self._cur_doc =3D None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chun= ks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + raise QAPISemError(self._cur_doc.info, + 'Level %d subheading found outside a ' + 'level %d heading' + % (level, level - 1)) + snode =3D self._make_section(heading) + self._active_headings[level - 1] +=3D snode + self._active_headings =3D self._active_headings[:level] + self._active_headings.append(snode) + return snode + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] +=3D node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + If the freeform document starts with a line of the form + '=3D Heading text', this is a section or subsection heading, with + the heading level indicated by the number of '=3D' signs. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc =3D doc + + text =3D doc.body.text + 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(' ') + node =3D self._start_new_heading(heading, len(leader)) + if text =3D=3D '': + return + else: + node =3D nodes.container() + + self._parse_text_into_node(text, node) + self._cur_doc =3D None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext =3D re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist =3D ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start li= ne + # of the doc comment, rather than the actual location of the e= rror. + # Being more precise would require overhaul of the QAPIDoc cla= ss + # to track lines more exactly within all the sub-parts of the = doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + # Append a blank line -- in some cases rST syntax errors get + # attributed to the line after one with actual text, and if there + # isn't anything in the ViewList corresponding to that then Sphinx + # 1.6's AutodocReporter will then misidentify the source/line loca= tion + # in the error message (usually attributing it to the top-level + # .rst file rather than the offending .json file). The extra blank + # line won't affect the rendered output. + rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.li= ne) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_node(self): + """Return the root docutils node which makes up the document""" + return self._top_node --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146723; cv=none; d=zohomail.com; s=zohoarc; b=Ip56WQnU6iSGdgaqL3Ap809UJYWe5Z7JtYb3WhDgyI1OoFDuAQ6lwqE7bIMmDXCT4KhVbt9q7jpsq6+FUkNCafdYOR2wguxz6hP5Da4TXSPo74O+6U53pKToK3g0iz3x6xVHOggznKMBzB/2vuH3b1UVRQXpaZjJsXpw/n7H/SA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146723; 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=NNqDpq0iJIveYhg6oQ1eKKTueZtlSKNrRW9Qrz0iOMU=; b=Ga4nUWuPm+MUuWTdGWlazinhW7PDH1m5PtPEgLf8vVkNYq75+DT6fmHV9DR7GmOPl7GHWpHGZABwuNS7D+a2D8FsG1SIX3Oro4WbeLQn5PHOf4ROhcc/h575heQ/PPH1L2I2Eu7G+zp6ZBNRI10rTGatTgl17Mt9Gr60EcD3bVo= 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 1741146723005508.9634511191209; Tue, 4 Mar 2025 19:52:03 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkb-00031K-Cm; Tue, 04 Mar 2025 22:48: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 1tpfkK-0002XG-Hg for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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 1tpfkI-0006Ka-Gz for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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-543-DqlNMidOP0OVVIQR7paxRg-1; Tue, 04 Mar 2025 22:48:26 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 C0B2D1800263; Wed, 5 Mar 2025 03:48:25 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3DF7E1956095; Wed, 5 Mar 2025 03:48:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146512; 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=NNqDpq0iJIveYhg6oQ1eKKTueZtlSKNrRW9Qrz0iOMU=; b=YggtJKPs1v5r0DBccKpft/7pIb+KQmpNQZL1W/Dgy825Y/2pp9O5RpSs+9gYG8qg1SAzhD Uiamauj7NXNL5gtKI/T5zVff3RgyUOKHP+fm/yq7Hn/q+HUTSY5ajPfDYqxXRyaaYVONHp t7gjlXWAXwqvgdUk7OcBwsbgqdAcCls= X-MC-Unique: DqlNMidOP0OVVIQR7paxRg-1 X-Mimecast-MFC-AGG-ID: DqlNMidOP0OVVIQR7paxRg_1741146505 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 35/57] docs/qapidoc: Fix static typing on qapidoc.py Date: Tue, 4 Mar 2025 22:45:44 -0500 Message-ID: <20250305034610.960147-36-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146723680019000 Content-Type: text/plain; charset="utf-8" Now that the legacy code is factored out, fix up the typing on the remaining code in qapidoc.py. Add a type ignore to qapi_legacy.py to prevent the errors there from bleeding out into qapidoc.py. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 40 ++++++++++++++++++++++------------- docs/sphinx/qapidoc_legacy.py | 1 + 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f4abf42e7bf..5246832b68c 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -24,17 +24,18 @@ https://www.sphinx-doc.org/en/master/development/index.html """ =20 +from __future__ import annotations + import os import sys -from typing import List +from typing import TYPE_CHECKING =20 from docutils import nodes from docutils.parsers.rst import Directive, directives from qapi.error import QAPIError -from qapi.gen import QAPISchemaVisitor -from qapi.schema import QAPISchema +from qapi.schema import QAPISchema, QAPISchemaVisitor =20 -from qapidoc_legacy import QAPISchemaGenRSTVisitor +from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore from sphinx import addnodes from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError @@ -42,6 +43,15 @@ from sphinx.util.nodes import nested_parse_with_titles =20 =20 +if TYPE_CHECKING: + from typing import Any, List, Sequence + + from docutils.statemachine import StringList + + from sphinx.application import Sphinx + from sphinx.util.typing import ExtensionMetadata + + __version__ =3D "1.0" =20 =20 @@ -53,11 +63,11 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor): schema file associated with each module in the QAPI input. """ =20 - def __init__(self, env, qapidir): + def __init__(self, env: Any, qapidir: str) -> None: self._env =3D env self._qapidir =3D qapidir =20 - def visit_module(self, name): + def visit_module(self, name: str) -> None: if name !=3D "./builtin": qapifile =3D self._qapidir + "/" + name self._env.note_dependency(os.path.abspath(qapifile)) @@ -65,10 +75,10 @@ def visit_module(self, name): =20 =20 class NestedDirective(Directive): - def run(self): + def run(self) -> Sequence[nodes.Node]: raise NotImplementedError =20 - def do_parse(self, rstlist, node): + def do_parse(self, rstlist: StringList, node: nodes.Node) -> None: """ Parse rST source lines and add them to the specified node =20 @@ -93,15 +103,15 @@ class QAPIDocDirective(NestedDirective): } has_content =3D False =20 - def new_serialno(self): + def new_serialno(self) -> str: """Return a unique new ID string suitable for use as a node's ID""" env =3D self.state.document.settings.env return "qapidoc-%d" % env.new_serialno("qapidoc") =20 - def transmogrify(self, schema) -> nodes.Element: + def transmogrify(self, schema: QAPISchema) -> nodes.Element: raise NotImplementedError =20 - def legacy(self, schema) -> nodes.Element: + def legacy(self, schema: QAPISchema) -> nodes.Element: vis =3D QAPISchemaGenRSTVisitor(self) vis.visit_begin(schema) for doc in schema.docs: @@ -109,9 +119,9 @@ def legacy(self, schema) -> nodes.Element: vis.symbol(doc, schema.lookup_entity(doc.symbol)) else: vis.freeform(doc) - return vis.get_document_node() + return vis.get_document_node() # type: ignore =20 - def run(self): + def run(self) -> Sequence[nodes.Node]: env =3D self.state.document.settings.env qapifile =3D env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir =3D os.path.dirname(qapifile) @@ -185,7 +195,7 @@ def _highlightlang(self) -> addnodes.highlightlang: ) return node =20 - def admonition_wrap(self, *content) -> List[nodes.Node]: + def admonition_wrap(self, *content: nodes.Node) -> List[nodes.Node]: title =3D "Example:" if "title" in self.options: title =3D f"{title} {self.options['title']}" @@ -231,7 +241,7 @@ def run(self) -> List[nodes.Node]: return self.admonition_wrap(*content_nodes) =20 =20 -def setup(app): +def setup(app: Sphinx) -> ExtensionMetadata: """Register qapi-doc directive with Sphinx""" app.add_config_value("qapidoc_srctree", None, "env") app.add_directive("qapi-doc", QAPIDocDirective) diff --git a/docs/sphinx/qapidoc_legacy.py b/docs/sphinx/qapidoc_legacy.py index 679f38356b1..13520f4c26b 100644 --- a/docs/sphinx/qapidoc_legacy.py +++ b/docs/sphinx/qapidoc_legacy.py @@ -1,4 +1,5 @@ # coding=3Dutf-8 +# type: ignore # # QEMU qapidoc QAPI file parsing extension # --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146707; cv=none; d=zohomail.com; s=zohoarc; b=klut4nU9bEayAg9Hv3B3kbX7k5mDY+JF8Jk4Q3dsQzam6GICuE3YTojn7ma+0DUHwESC1uKBvUjyrcHDNfeXBKDEDQkjwoF6rOawI0dcUn3qEL3OAZrPOO2W6cyX0r2BO/Ws69oV1I+wv938OKkaUycQIm9XWfxCc5lVF5ylggw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146707; 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=RqE/XUlSLn9cG8sCfFSRS5q3COLWGY4MaWr5eyBqqf8=; b=Bm+Kwg23jur8qXiX1rrVhJe308xcZlYeSv71u+fBGTKgfvBCXkF/vJlWNTyr4Z12DeVmBP5Xja5CORdBmXjPuij7//LjzythG4mFL8nMqhI3E+nAM5FDKN5gww115t8KJYhRrqnNCJf9DKVydsu5vstSgYmp6jYleD4Xx96s4rY= 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 1741146707740335.261901491976; Tue, 4 Mar 2025 19:51:47 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkb-00034Y-Ii; Tue, 04 Mar 2025 22:48: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 1tpfkM-0002ar-Px for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:40 -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 1tpfkJ-0006Ko-CM for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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-498-_jmXL0zAN-Ot_csB5yUgJA-1; Tue, 04 Mar 2025 22:48:29 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 6A9631800349; Wed, 5 Mar 2025 03:48:28 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id EB6571956095; Wed, 5 Mar 2025 03:48:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146514; 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=RqE/XUlSLn9cG8sCfFSRS5q3COLWGY4MaWr5eyBqqf8=; b=K2QH+a3XcB4iZmuF1T1clKfXU8onCaQDd/OP4x07CL6dyEupJHzJF97jvmeXaSeS8M/5wj 9+IohAMVaBcm8/qtAnOmLsX9fFPpnYVTrF1pDcT4o/Xf0ypbIgsu/MVEySxRWQf7Zn2dMJ fzNACPQDP1PnqqyaTgKeNwgpui8k9v8= X-MC-Unique: _jmXL0zAN-Ot_csB5yUgJA-1 X-Mimecast-MFC-AGG-ID: _jmXL0zAN-Ot_csB5yUgJA_1741146508 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 36/57] do-not-merge Date: Tue, 4 Mar 2025 22:45:45 -0500 Message-ID: <20250305034610.960147-37-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146709084019100 Content-Type: text/plain; charset="utf-8" Add strict typing to qapidoc.py for the remainder of this series. Signed-off-by: John Snow --- scripts/qapi-lint.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/qapi-lint.sh b/scripts/qapi-lint.sh index 0e3ff002b69..dd3e6eb84c5 100755 --- a/scripts/qapi-lint.sh +++ b/scripts/qapi-lint.sh @@ -35,7 +35,7 @@ if [[ -f ../docs/sphinx/qapi_domain.py ]]; then pushd ../docs/sphinx =20 set -x - mypy --strict $files + PYTHONPATH=3D../../scripts/ mypy --follow-untyped-imports --strict $fi= les qapidoc.py flake8 --max-line-length=3D80 $files qapidoc.py isort -c $files qapidoc.py black --line-length 80 --check $files qapidoc.py --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146706; cv=none; d=zohomail.com; s=zohoarc; b=Ocrb4sh0ndwpTDtRtGmF/TL66sEjHp3azRuHgQa2nKS2D3QPqc74SO4jyW/X8eJ0WMfL+1XnjvaxWuKcMUo7kHsfqCJsIuVR2bLjGeaj/Hvfqz9VO+cb9spCLYbMdqlO05584uxj5guCDYRMfHl1Nvy1gKGjvGymaZBsum79me8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146706; 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=BQvE/HneCGz1g30jzw3OwriCq5NXZt5xVT54X3KVDic=; b=QrGxwOwfeLgo2vlnWrtO/Er8NNAtuKpdHrA1l5mUC35oJP9LgM4Hn3gaW9Avu8GVpkuqpPi9OCuFEFOMp5h3PG9VhR7IC/yfNsT+pOrRrmuXZNPRgLFBV8A0xEYK3AV2Aik34AhtSaWR+aSLS9N75Ee/YzJtp9Z7WCIf9TlpaE4= 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 1741146706539342.1890534171007; Tue, 4 Mar 2025 19:51:46 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfke-0003ZK-Tr; Tue, 04 Mar 2025 22:48: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 1tpfkM-0002as-QN for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:40 -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 1tpfkK-0006L6-TC for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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-208-usrEoMjgPcmZQOB_j5Ojqw-1; Tue, 04 Mar 2025 22:48:33 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 1AED8180025A; Wed, 5 Mar 2025 03:48:32 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 032C61956095; Wed, 5 Mar 2025 03:48:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146516; 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=BQvE/HneCGz1g30jzw3OwriCq5NXZt5xVT54X3KVDic=; b=ZzDfq978mT0MsoIb5DN5Sra29o+YVPIGySohP0I/PkK/RmD4YwQQJ1bgjtlKabfi4NAb5s BD7uJ5WYZi0Uem1GZfiydP/zUqp0Bg0QL17czg+SKAFI0hk5/YT/1SWCdd8N0zVbaojT6Q j2d6EfAX2ksf0cgGpP1uzuQzNapJlaU= X-MC-Unique: usrEoMjgPcmZQOB_j5Ojqw-1 X-Mimecast-MFC-AGG-ID: usrEoMjgPcmZQOB_j5Ojqw_1741146512 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 37/57] docs/qapidoc: add transmogrifier class stub Date: Tue, 4 Mar 2025 22:45:46 -0500 Message-ID: <20250305034610.960147-38-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146709151019100 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 --- docs/sphinx/qapidoc.py | 73 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5246832b68c..c243bb6faaa 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,14 +26,17 @@ =20 from __future__ import annotations =20 +from contextlib import contextmanager import os import sys from typing import TYPE_CHECKING =20 from docutils import nodes from docutils.parsers.rst import Directive, directives +from docutils.statemachine import StringList from qapi.error import QAPIError from qapi.schema import QAPISchema, QAPISchemaVisitor +from qapi.source import QAPISourceInfo =20 from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore from sphinx import addnodes @@ -44,9 +47,12 @@ =20 =20 if TYPE_CHECKING: - from typing import Any, List, Sequence - - from docutils.statemachine import StringList + from typing import ( + Any, + Generator, + List, + Sequence, + ) =20 from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata @@ -55,6 +61,67 @@ __version__ =3D "1.0" =20 =20 +class Transmogrifier: + def __init__(self) -> None: + 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) -> Generator[None]: + 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. + self.add_line_raw(content, info.fname, info.line) + + def add_lines( + self, + content: str, + info: QAPISourceInfo, + ) -> None: + 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) + assert isinstance(line, int) + # 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) + + class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module =20 --=20 2.48.1 From nobody Wed Apr 2 13:05:53 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146587; cv=none; d=zohomail.com; s=zohoarc; b=RfzegjDBOfwrQVKbk1a0CuNZdWoHGZBV/BllkFfATi0DQDUjb9uJhRTeG7J/0skw1eK078fEO5f65vPSoEZhf/De+Qhetk7kHFM2c3TR/Mni06WyKOGrmaudOS63BMjiA2TwxclkVfZB0xYTAJKqQRTxd5fgoxqbvHkfTArVwE4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146587; 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=7RoKJbqlQB3AZV623n4GqGylO66vrkMFX3kGFcnwnYw=; b=B4kT/J0WIviFvZHT3MpROJ2fU+easU661AjF6c2Wmd3VzFa3b+7shwPvTNchKVyDKIyEh5u0IKihADCClPWPI/oMdsaMBoUFUKhcnS3mVD1QuP6X3j0d0NdlegjBCF+Q406VQKgPreIH3Gf5PbIKN56kgpklOz61W5FRMsWoGf8= 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 1741146587047619.4123304455557; Tue, 4 Mar 2025 19:49:47 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkg-0003hj-Uv; Tue, 04 Mar 2025 22:48: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 1tpfkW-0002kY-M0 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:50 -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 1tpfkU-0006MY-1t for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:47 -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-631-7NnxBmKoN8iQ4naF68p7Vg-1; Tue, 04 Mar 2025 22:48:37 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 39E9E1800262; Wed, 5 Mar 2025 03:48:36 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id AAB941956095; Wed, 5 Mar 2025 03:48:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146525; 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=7RoKJbqlQB3AZV623n4GqGylO66vrkMFX3kGFcnwnYw=; b=FCr+lpiXh2B0BlIVlen3stqKzJ9gyG2OxSVcb+Gn2qr/4C617LC2aILdO+8hAks3X9SUuA ziny4UkG+wqaK+mTp56Fa2pk7tEZNYKyVsZRDNXw6hOZjzDgeAEqFy2bNgpf5hdjuJMb/k Sw7Hvs6I/AO2TQsWN0aPMFLx5rgWy5w= X-MC-Unique: 7NnxBmKoN8iQ4naF68p7Vg-1 X-Mimecast-MFC-AGG-ID: 7NnxBmKoN8iQ4naF68p7Vg_1741146516 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 38/57] docs/qapidoc: add visit_module() method Date: Tue, 4 Mar 2025 22:45:47 -0500 Message-ID: <20250305034610.960147-39-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146588828019100 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 --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index c243bb6faaa..6de8c900543 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -28,6 +28,7 @@ =20 from contextlib import contextmanager import os +from pathlib import Path import sys from typing import TYPE_CHECKING =20 @@ -121,6 +122,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 class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146777; cv=none; d=zohomail.com; s=zohoarc; b=NRtcUIAu97uYD4CEfJW/NvjbjZR+GWEsBLDBNheL5n79tKZldqooZ9+wJj4dtezrNY1Me6XwjbmfBNPgo53wZJykYh8fuvt+L415elYHJfOAxafjaQ6DUFjkY8EZbDzkaLAGBpQC3xQoY/cp8ZX33TJAdChtiVYa/T9NVSfI//c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146777; 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=OaIZ1svi11y2mqVzTtd5Ur/R2Kbtc0ToikqKDdc0EMRsfKAr8n0P7m2ZpYhfQbTqj3GVSY9yudBilqX5oYpjaVxiUTLBImpGjrlE+w4J4/92mErPi4AzxJxQSQEnNM9mw5zxa6NDHXcfE65UUDdSEsG6AM3O9inWYvYRsqefC1Y= 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 1741146777197377.01949609294195; Tue, 4 Mar 2025 19:52:57 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfki-0003wM-VK; Tue, 04 Mar 2025 22:49:01 -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 1tpfkT-0002iZ-NK for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:48 -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 1tpfkS-0006ML-7V for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48: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-517-LxqjdrfrPPuupCcSo6FxRw-1; Tue, 04 Mar 2025 22:48:40 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 2A8381955BC1; Wed, 5 Mar 2025 03:48:39 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6F1C81956095; Wed, 5 Mar 2025 03:48:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146523; 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=HxCv6+A92tvPCrkLnoP1NEnprpc8WD9+NjhIAo7QWltK8kN7ydye3U1t+qoK96lLlixd84 SnI+bAkyoDifojEU2VlweAYy5Ke2G2mpA2rPTPni3t2PzFC5TDaOkSuv3NC5HFfECn4KSz fw0onX3myYbjUPOfccJ35Wd96uEzdyY= X-MC-Unique: LxqjdrfrPPuupCcSo6FxRw-1 X-Mimecast-MFC-AGG-ID: LxqjdrfrPPuupCcSo6FxRw_1741146519 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 39/57] qapi/source: allow multi-line QAPISourceInfo advancing Date: Tue, 4 Mar 2025 22:45:48 -0500 Message-ID: <20250305034610.960147-40-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146779380019100 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 --- 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146613; cv=none; d=zohomail.com; s=zohoarc; b=fvXBs/5YbnSiBHlpNFUtPr4zf+NL+SxmYbP+fc4u+UYz/zAUhe/m1J9MQty/6ZtEk3V+4C/8wVIXM+y85TMqYLsZVWWWgrs+8jJHKbiAsbOobtPkLc1BdSuD7PLigeR5zRy+WdvPuRRXQdn4hlyXDEmxNdJQeBVOt0hGzqS5ie4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146613; 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=Wk9kVkfc4LXryc5ue1ku8Wh0BN0iylKBPCMQqL6iSOQ=; b=YsymTz+tqkOKzGRBNgQA0iBNF6H31mWB1OEL1wLdMdIijO2wV2gBk713PV3LkQJ1VmBBs4AOMCdTI2VwrN3TWy4AtfpJCMpi4vdnmyNh5V49PCanVlcojctA1idvIuOcTj9IizBnA+17fQiDlQ6TggSC1y4wdRvRXCui+LSdvNg= 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 1741146613173657.940729317173; Tue, 4 Mar 2025 19:50:13 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflG-0005Jx-8L; Tue, 04 Mar 2025 22:49: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 1tpfkq-0004YY-8a for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:08 -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 1tpfko-0006P7-AQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:07 -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-287-XZsB4JzAPi-zwoFxdONgNg-1; Tue, 04 Mar 2025 22:48:44 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 296D9195418F; Wed, 5 Mar 2025 03:48:43 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id BAAF31956095; Wed, 5 Mar 2025 03:48:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146544; 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=Wk9kVkfc4LXryc5ue1ku8Wh0BN0iylKBPCMQqL6iSOQ=; b=iSSpM7gwVflyrytGZ1WHh9Nk4WxeYjEpaX73p04UfU81h658K0IObg7A0LUU1ClcqvS5Wq 8LzikHGFYoMP3smTK/omxV0w9Gsi/VhEacCNbp2hJCyOsGgK0TnCoYAcyw6Ml/gN46yFJ0 GGlxjP4/r2T0ZIYi8vyKYOYzmcUv+lQ= X-MC-Unique: XZsB4JzAPi-zwoFxdONgNg-1 X-Mimecast-MFC-AGG-ID: XZsB4JzAPi-zwoFxdONgNg_1741146523 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 40/57] docs/qapidoc: add visit_freeform() method Date: Tue, 4 Mar 2025 22:45:49 -0500 Message-ID: <20250305034610.960147-41-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146614932019100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 50 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6de8c900543..cf5dbb0133d 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -29,6 +29,7 @@ from contextlib import contextmanager import os from pathlib import Path +import re import sys from typing import TYPE_CHECKING =20 @@ -55,6 +56,8 @@ Sequence, ) =20 + from qapi.parser import QAPIDoc + from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata =20 @@ -130,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: QAPIDoc) -> 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 class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146785; cv=none; d=zohomail.com; s=zohoarc; b=Iz9dlA7YhHUM1QPyp/E5FJFR9U2EO5EywnTC22kFz8ksUvTjvniTNPyCv1/VORwwKui+7v26gsrGrkou7pGN8H3VDJYmKe6XgnFeJEfhQrYK5eniyDJmH/ueh1ByNVwoa7yKQ4hQUTus+MogmqfKHLCw93BYl7wricZh0EEg04A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146785; 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=LhfTvZSOFIKGzjAQ6Ymgn0Jsa6ARUZT0HLCMnY9mMyI=; b=b2UkHw23vCwMNyFuqpxmKJPAD11xhp4e0+6vpNQlZrObeCJMra6q7uOkvEqmjRZVqcC38ZkeEM0ueN0yQMgGI6tSWPsyOYo3NJa4wDQM0WCK/SDJDHOQwSsLlZiboyy5vQb/cJ0vGH6x+J+phc0FZL1pLAn0xIevziu5dz24PtY= 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 1741146785252942.2973008838577; Tue, 4 Mar 2025 19:53:05 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflD-0005Er-5b; Tue, 04 Mar 2025 22:49:32 -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 1tpfkm-0004Jr-Ox for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:05 -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 1tpfkl-0006On-28 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:04 -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-574-vCHpAMRCPMu07Gnvhyo9dQ-1; Tue, 04 Mar 2025 22:48:48 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 01C5A1955D4B; Wed, 5 Mar 2025 03:48:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B99D31956095; Wed, 5 Mar 2025 03:48:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146542; 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=LhfTvZSOFIKGzjAQ6Ymgn0Jsa6ARUZT0HLCMnY9mMyI=; b=ZYIegH5CBNnkNToWdC32STNeJbm1w3mofRCl9BPEH7O1dtB7EOE+4TevZWSZ2p29UwqB3o C9AQ9egK1PLbIqOAP07nmVUd06Xe8xzz3etyWGG6nVfoC2CJcuP/HfRg4DsqKpsAdCjFjE p6a/ksM1g9cfm36XhkpOaEJFjbDBTaI= X-MC-Unique: vCHpAMRCPMu07Gnvhyo9dQ-1 X-Mimecast-MFC-AGG-ID: vCHpAMRCPMu07Gnvhyo9dQ_1741146527 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 41/57] docs/qapidoc: add preamble() method Date: Tue, 4 Mar 2025 22:45:50 -0500 Message-ID: <20250305034610.960147-42-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146785900019000 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 --- docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index cf5dbb0133d..d8bf0073dfa 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -37,7 +37,12 @@ from docutils.parsers.rst import Directive, directives from docutils.statemachine import StringList from qapi.error import QAPIError -from qapi.schema import QAPISchema, QAPISchemaVisitor +from qapi.parser import QAPIDoc +from qapi.schema import ( + QAPISchema, + QAPISchemaDefinition, + QAPISchemaVisitor, +) from qapi.source import QAPISourceInfo =20 from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore @@ -56,8 +61,6 @@ Sequence, ) =20 - from qapi.parser import QAPIDoc - from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata =20 @@ -125,6 +128,38 @@ 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: QAPISchemaDefinition) -> 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() + assert ent.info + # 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. + assert feat.info + 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146797; cv=none; d=zohomail.com; s=zohoarc; b=LrOUnQ9XQkI9gJd4USi8CMvlQ+g4xGjtclhfq3rp431v8I0D9s56OQ84NBPoms4xhr+sI6OItDtjcFcB+aeXzs9OTx63kQHr2r863iekiAUIRL0ThBMeO0CLpf6E5WEeDikckJZV/0wItOyQjOnsFR8fNIW7LcOJ1on6yv+WS8Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146797; 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=Q3zFM7VB6vNHTb+4RTh2NfCuSvLj4EjSl3ab/FSW5yI=; b=ZzSqcXp0l3b5OKF9wdsgsyEebThGHmjiSJM3FW2tfvoFwFetnP9MvcSFr3IN2tHI7Sq2gbe+XWy+cNfBiggauNo0zJ+jMkbHzfR7+nq+J/jBtHMgoTbJ/vmhHWiPtNBFXho6bOPxEUiU+oVP+YJPAvS8Vfu9Ec0SAGXg5h2iZhU= 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 174114679722129.12287340187015; Tue, 4 Mar 2025 19:53:17 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfkv-0004pe-No; Tue, 04 Mar 2025 22:49: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 1tpfkn-0004KD-8o for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:05 -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 1tpfkl-0006Oy-OD for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:05 -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-447-Y_gWjYh4MqST-n-vKIG_7w-1; Tue, 04 Mar 2025 22:48:51 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 3C12418001D6; Wed, 5 Mar 2025 03:48:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4AAF21956095; Wed, 5 Mar 2025 03:48:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146542; 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=Q3zFM7VB6vNHTb+4RTh2NfCuSvLj4EjSl3ab/FSW5yI=; b=dqFVb7IoTwnpP1IiCDTl2wZGK3oM8BVwPmgYMjO02W0BYzHL9zAug22gzAa9f79HFYZVGw PBsFAXuXS4ZjD9WNfUeYkbzCbjMD8olwVAiGXjVm5u7H0lo6EsppwCb93H/7gJsG2f0XZP xLZsDYj9vG/2+p7Wf9OOzB1rp72042s= X-MC-Unique: Y_gWjYh4MqST-n-vKIG_7w-1 X-Mimecast-MFC-AGG-ID: Y_gWjYh4MqST-n-vKIG_7w_1741146530 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 42/57] docs/qapidoc: add visit_paragraph() method Date: Tue, 4 Mar 2025 22:45:51 -0500 Message-ID: <20250305034610.960147-43-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146799563019100 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 --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d8bf0073dfa..b96445f0802 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -130,6 +130,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: QAPISchemaDefinition) -> None: """ Generate option lines for qapi entity directives. --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146657; cv=none; d=zohomail.com; s=zohoarc; b=c93QaAVhez30PPvxRMhWgVOrsGUGKTM+S/2t6/LJLx+I5uCdJWdj/g2NTK52emOad7w47ZGPI5Q8OkyzYSM6gnvbRLl0wssRP9QzV5Om7Z5h8664rGAGJSUHom7z8YqhXdci8v9td/Bn/Pj8SiAOhdei6fupdPa3sIbrZ956wbY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146657; 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=vIGc94cR2Y+s/vJQEUhpco6eHNP2rFHQf6xGDS1RUBk=; b=Q0vVcD9jy8S/pi4hotiif7bp6BhcvcX5tsLYY+eMi0+RgKZoEv2IoWZ2QWaB+EYZ6Z/zhuYgJgwkhLp1f4THNCu9QLBTnjirEiFllAcJ4YpsixM4P9Ht205qxGOX5qaF7Yao3+lzGUUiCx4ITkc8U+w+/JQzhDSqsX+ryYCk9cU= 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 1741146657863566.3323429308646; Tue, 4 Mar 2025 19:50:57 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfko-0004Bl-KJ; Tue, 04 Mar 2025 22:49:06 -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 1tpfkg-0003lq-Ug for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:59 -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 1tpfkf-0006Np-IA for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:48:58 -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-616-kQEU3xerNK-MVOK9RhwzIw-1; Tue, 04 Mar 2025 22:48:55 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 56E2F180AF4A; Wed, 5 Mar 2025 03:48:54 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 846261956095; Wed, 5 Mar 2025 03:48:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146537; 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=vIGc94cR2Y+s/vJQEUhpco6eHNP2rFHQf6xGDS1RUBk=; b=QYsP84JKp7XGJZi9tZTW0uIOU70cxsiahZjn1lrB/GH01C/F28uC4gtR0mi8a1zOgOH3vN dA9O8JkVoJPHYLoQAtiU3vfYe3tSR6KuGPFFkUe5si8w8bwJdL/rmNIk5n5HgS0h8Z22q2 nnXybm4SyVV+cC5XX5m/3KX2FEEHXvw= X-MC-Unique: kQEU3xerNK-MVOK9RhwzIw-1 X-Mimecast-MFC-AGG-ID: kQEU3xerNK-MVOK9RhwzIw_1741146534 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 43/57] docs/qapidoc: add visit_errors() method Date: Tue, 4 Mar 2025 22:45:52 -0500 Message-ID: <20250305034610.960147-44-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146659501019000 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 --- docs/sphinx/qapidoc.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b96445f0802..14feafe866e 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -139,6 +139,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: QAPISchemaDefinition) -> None: """ Generate option lines for qapi entity directives. --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146774; cv=none; d=zohomail.com; s=zohoarc; b=mnomxYFCti9GgFwAS0yAqtwVgwT7VeAZOtg9aspGo2sDuI3D2+2W23dikDMf+EGqp3PCrxxfksMUYCEjMzzvTxEk7qxaYUMgpiRfVVgaVOAimOwlstFs/FJFCKiC1hIGeFGnhYY5FMUfOq3RZe1rUaF2n/h8MipMyyalb/V8Kdw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146774; 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=hyoOxfuL+eN7sxGkqJtJc7tjE8pjAxa9kZ6Hj/epo/4=; b=F7CmjbusSpacUFKNGEfnmcTBElgGUae9RiNL3JZ00Z3H3KYrJPXMM97710+DdARtjg9cW4fVjpD0c+E25898j6C20yQAyvzX+ubb0ZlTeGHo1ebh5EtnXfWXHNRTpIQFh9sWnkc8mWaP7Q2sD4LAIwChUYrFHdEPvxtdNwgr2pw= 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 17411467748259.209896127022375; Tue, 4 Mar 2025 19:52:54 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflD-0005Fc-C4; Tue, 04 Mar 2025 22:49: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 1tpfku-0004tU-Hi for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:13 -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 1tpfks-0006QA-63 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:11 -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-668-vtyZCdwJOuiXXileYiFiJw-1; Tue, 04 Mar 2025 22:48:59 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 798F51801A00; Wed, 5 Mar 2025 03:48:58 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C7DD31955DDD; Wed, 5 Mar 2025 03:48:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146549; 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=hyoOxfuL+eN7sxGkqJtJc7tjE8pjAxa9kZ6Hj/epo/4=; b=YDQcgeDzJ242aEA3J+FgrSnKL32BXcESosijsTVikgKAUYEpCHixZNyn6O5IiapVIUkVkW sDBwfoZPrLLSvSxTIWp6d5P2JAXu6fSq8u12Zk+IvpRXksNPOhEA2TYaxGUcctJ82i2jzP HfHYQbw/LGZJQmQulv5rySTXA3kMVUU= X-MC-Unique: vtyZCdwJOuiXXileYiFiJw-1 X-Mimecast-MFC-AGG-ID: vtyZCdwJOuiXXileYiFiJw_1741146538 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 44/57] docs/qapidoc: add format_type() method Date: Tue, 4 Mar 2025 22:45:53 -0500 Message-ID: <20250305034610.960147-45-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146775855019000 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 --- docs/sphinx/qapidoc.py | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 14feafe866e..0f895a3624a 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -40,7 +40,13 @@ from qapi.parser import QAPIDoc from qapi.schema import ( QAPISchema, + QAPISchemaArrayType, QAPISchemaDefinition, + QAPISchemaEnumMember, + QAPISchemaFeature, + QAPISchemaMember, + QAPISchemaObjectTypeMember, + QAPISchemaType, QAPISchemaVisitor, ) from qapi.source import QAPISourceInfo @@ -58,7 +64,9 @@ Any, Generator, List, + Optional, Sequence, + Union, ) =20 from sphinx.application import Sphinx @@ -128,6 +136,30 @@ 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: Union[QAPISchemaDefinition | QAPISchemaMember] + ) -> 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: + assert isinstance(qapi_type, QAPISchemaType) + tmp =3D qapi_type.doc_type() + assert tmp + ret =3D tmp + if optional: + ret +=3D "?" + + return ret + # Transmogrification helpers =20 def visit_paragraph(self, section: QAPIDoc.Section) -> None: --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146722; cv=none; d=zohomail.com; s=zohoarc; b=WSCv+ww2G7TxllTg5hR89lQOJm0LXn4ZeRMZKBdGs6e7fPzulevqK83+vTjOaZvf3vvsdfVALOeHxkZ4sCLSWEBlX01vZVrBD1I+SSRVgbgjkJbLtX+2Dkx5I+iyfSTUSvST7xvhthpA56OQ7aZlJyNy2ZDsbeKGjRbLID4tV94= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146722; 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=JuA7SVDgD0ex81fpF0cRX+zQ5amNxByPpkZFbXngsX4=; b=mlh5vKGjZfjJy2RR+RBXHQZIpE16Lf+qtNFrZceotDSgCI4a2/NNxVsUEzQvK9Bs2htzKudXYlhW6NAY8sPXAySzgrs3eKJzD7WSQLcE1RuHgF9QE5iyTmJ8JyjLNLszqFQ8TS5F8dGA7GZX72QFY+lIp2OIy3sk6+rVXu1DeTg= 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 1741146722648713.127919418945; Tue, 4 Mar 2025 19:52:02 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflK-0005bT-WB; Tue, 04 Mar 2025 22:49: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 1tpfkp-0004SR-Lj for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:07 -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 1tpfkn-0006PD-S8 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:07 -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-647-2NFrj4LpPnacCZNkJaENuQ-1; Tue, 04 Mar 2025 22:49:03 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 377BA18001D6; Wed, 5 Mar 2025 03:49:02 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1D3651956095; Wed, 5 Mar 2025 03:48:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146544; 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=JuA7SVDgD0ex81fpF0cRX+zQ5amNxByPpkZFbXngsX4=; b=a/xeN4h/ZlO0yVfoOtUNH4Nc34Ec8TnkWa/mniNhjQ0al5jPNTpNgmAq0esr+8nYjf6rjA fyjfAp5LWaE1+jw5m9nVRvHwxpbKhnnhHpIbufydsbO5BOCSiAeR4mH8AUP3PKZGsjAEpL 1wQb2GWsK1iulh8RkD3tiLrinwDr20s= X-MC-Unique: 2NFrj4LpPnacCZNkJaENuQ-1 X-Mimecast-MFC-AGG-ID: 2NFrj4LpPnacCZNkJaENuQ_1741146542 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 45/57] docs/qapidoc: add add_field() and generate_field() helper methods Date: Tue, 4 Mar 2025 22:45:54 -0500 Message-ID: <20250305034610.960147-46-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146723773019000 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 --- docs/sphinx/qapidoc.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 0f895a3624a..b87ce288837 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -136,6 +136,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: Union[QAPISchemaDefinition | QAPISchemaMember] ) -> Optional[str]: @@ -160,6 +174,16 @@ def format_type( =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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146780; cv=none; d=zohomail.com; s=zohoarc; b=jlTjyh4S26mnxy6lUkSM2v3SZebwYVcA9vqHbEYo9PQR1T35LciTRPGxD+yPnD+G8/rdRxfd7sGrI/tYSF39Ul0fqVRPMMT9enfkZAi2WysZk/T1M1+GKUInDeVGSGCF3ERlHjZtCw+mBRXrk1rfv7ZqD24EM5g+KmWbQ4ERVGU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146780; 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=OsISB484xmR91C9VkjAj0P0bum4J91L8AI+R4ChrXF0=; b=CIjX1QB6BJhBF8i0x9rjfUM6oOHClOCBhohxuDl86EC2Ag4BLPV/FZofrd2Bcy6qq6L7iW19SU3Yq6DKRAuI8sdnKZOk/NbePyGF+KTwMf9GKcYr8Pr3yXFVrcC9+WPq0zeoe1aQlmHiRCgFviqvcf5OHiXiFY1C9Sy8Y53bOqY= 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 1741146780227669.2633425201562; Tue, 4 Mar 2025 19:53:00 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflL-0005jx-Ls; Tue, 04 Mar 2025 22:49: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 1tpfks-0004po-UJ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:11 -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 1tpfkr-0006Q1-A2 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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-433-L_OkiZ8oNZC6sC5KqjXBTg-1; Tue, 04 Mar 2025 22:49:07 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 262A91954B32; Wed, 5 Mar 2025 03:49:06 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C44871956095; Wed, 5 Mar 2025 03:49:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146548; 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=OsISB484xmR91C9VkjAj0P0bum4J91L8AI+R4ChrXF0=; b=auJ4U2KpfyENSRXJcyS1K87vppuqa6cRHpjlKbBwXAedxE7IHICu6BbfqSIgOV/C3MuY1D zkdMJDBmnCGpaCICnzpV8vDb7iRZcN2oTzcQpRvaV9vo+xDinot6gsfwtctJSRIADFgZLE 7hCLHMsamAdc+ykemSHMEbMn7UyfsbM= X-MC-Unique: L_OkiZ8oNZC6sC5KqjXBTg-1 X-Mimecast-MFC-AGG-ID: L_OkiZ8oNZC6sC5KqjXBTg_1741146546 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 46/57] docs/qapidoc: add visit_feature() method Date: Tue, 4 Mar 2025 22:45:55 -0500 Message-ID: <20250305034610.960147-47-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146783396019100 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 --- docs/sphinx/qapidoc.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b87ce288837..eaea19af7ac 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -195,6 +195,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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146742; cv=none; d=zohomail.com; s=zohoarc; b=SFyDShu7sOhTlu3sidFUk+sv+vfoyBSQ7ec5nud/LdwBmIXOwup2ZK7/5VDhyJM13rckivmY58H3HrilZIwHmjVp5969ndnEunEloP1evOMwzQLsYStTAI2umuufjJTclDtD+Ua13JGi1LoN5EaKioDcml6o/524cMCtZcs7ogM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146742; 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=eIml+bdV/p1otVFgQ8rtuT2HtOqCWjt8m6j6hmwpw64=; b=lXaCC7vvLfarwH2WAj+YZ2bvhOf+TN1dQ9hHNo/nTCiU1fVlllnDORAx/VBmx9PnvldAKGPW++WF7/ywyPCpJrMMIctW64egDQIGV9n69RetHzLBk3AHg7EeCmYZwSla/SJqsEwVzh3lECSFGr/r9WR8HYkeewomhldGA9IcLXM= 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 1741146741924869.687894591455; Tue, 4 Mar 2025 19:52:21 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflP-0006BI-PS; Tue, 04 Mar 2025 22:49:44 -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 1tpfkw-0004u0-9i for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:19 -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 1tpfku-0006Qe-IQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:13 -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-31-JEnN4Il1MCCX6EhzA19pyA-1; Tue, 04 Mar 2025 22:49:10 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 77F7A1955BC5; Wed, 5 Mar 2025 03:49:09 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 188341956095; Wed, 5 Mar 2025 03:49:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146551; 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=eIml+bdV/p1otVFgQ8rtuT2HtOqCWjt8m6j6hmwpw64=; b=cXO0s5ZZlRyApGMljYpa+dsTdc6spjDHAam1kWUTl03BD2e9nFSM93+4sUzUMidiL33I5U h8IvoD6GknNn7NROlEA65w2VDAJaLFAlbQmh1yxB5yvdqLMmrPT1Yuk6Y5Zb9b80ZL2IqC obF/IopxoIovHu+YO9rByZTwv9MVcxE= X-MC-Unique: JEnN4Il1MCCX6EhzA19pyA-1 X-Mimecast-MFC-AGG-ID: JEnN4Il1MCCX6EhzA19pyA_1741146549 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 47/57] docs/qapidoc: prepare to record entity being transmogrified Date: Tue, 4 Mar 2025 22:45:56 -0500 Message-ID: <20250305034610.960147-48-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146743291019100 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. This patch is front-loaded for the sake of type checking in the forthcoming commits before visit_entity() is ready to be added. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index eaea19af7ac..834f12ba6e9 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -78,9 +78,15 @@ =20 class Transmogrifier: def __init__(self) -> None: + self._curr_ent: Optional[QAPISchemaDefinition] =3D None self._result =3D StringList() self.indent =3D 0 =20 + @property + def entity(self) -> QAPISchemaDefinition: + 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146675; cv=none; d=zohomail.com; s=zohoarc; b=Za9px5qWNsJ9FFoxZXkEvm9dhTzJNn+p4iEn8d1Aeq340fCtiAZSA3sKd3HmZlgjZ1Vj75s4f/tzoEbFL3my0n/4qqXxtZQ3kejOlmtc/hsZg2UGB6W86gRbERyPzC0FnpfR5/97Qt/oJatnOYahD1/lIByt2edohZhhI0RM92I= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146675; 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=OeLdWRvpxy5heHacuodQ2Q9wmnARCS6kGdYbSgvKGA8=; b=YZGWnHP56txB8S2bv31+bB+b6mjIidfSg0Caa1XFky8Q/6BRrJ2eDtVuczrqb5JNowgwNqopRslgS2jlemheFvo8baIGVlswzb8O8MncCb23AyRFtgk0QuykSSpWqKb386JqF9Y/lapuQujHuhe/jJSY/BnAg3nrwpzlSazKmn4= 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 174114667588729.334911853426092; Tue, 4 Mar 2025 19:51:15 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflM-0005pe-T8; Tue, 04 Mar 2025 22:49: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 1tpfl1-0004ug-3o for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:20 -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 1tpfkz-0006Rb-Eo for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:18 -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-43-qdTEf0mePXu6kEfKNycpZA-1; Tue, 04 Mar 2025 22:49:13 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 A1316180882F; Wed, 5 Mar 2025 03:49:12 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2AF441956095; Wed, 5 Mar 2025 03:49:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146556; 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=OeLdWRvpxy5heHacuodQ2Q9wmnARCS6kGdYbSgvKGA8=; b=ILke5ZSNSmjZfiQaUA1sZ5DspTYBOghljlS58HPAQwDlyoKyh9oXzx9ERySNnls4sv37IX HT+BuyTZs7WVFdlVXynPgiEwGoELoE/nToSikohz+MdTfw4vINN8+a20999Rxx0p3/nVq8 r1vrbAlOdb3yjIInnIfq9Ozl5l42BgQ= X-MC-Unique: qdTEf0mePXu6kEfKNycpZA-1 X-Mimecast-MFC-AGG-ID: qdTEf0mePXu6kEfKNycpZA_1741146552 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 48/57] docs/qapidoc: add visit_returns() method Date: Tue, 4 Mar 2025 22:45:57 -0500 Message-ID: <20250305034610.960147-49-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146677037019100 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 --- docs/sphinx/qapidoc.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 834f12ba6e9..6458790fe55 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -41,6 +41,7 @@ from qapi.schema import ( QAPISchema, QAPISchemaArrayType, + QAPISchemaCommand, QAPISchemaDefinition, QAPISchemaEnumMember, QAPISchemaFeature, @@ -210,6 +211,20 @@ 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 typ + 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146803; cv=none; d=zohomail.com; s=zohoarc; b=RdkV+YYbt3zdLMj4AEUz3deo4dQI/J5idZYRifNaT8ZTpBNG0CdoUSSYiD4+9g4bx5gCpgMT3mEYFp0fPMr34FmTWb8K4iTtwTbrxeRUbasbDyRVWqVERvyAVe1kn1v0WI84zSmZqA0vBXCcnCztStTo0Qn86rUuaaPR6Ty/lmg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146803; 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=2QNFdU44Nnk/IStMvTW0EZuQ/J//zx6IVlDhhJASnvc=; b=ba8hh8pqGe87Ae7szQmGV+rZrPbCAjqXbznzk03tbD3NeNs90rlZKHqFwJpQ98Mlf6BRnuBmaBWHqDOI0JStjL+UUfWm/GeITIvS5UXiFILLOSlMBbG4gDUier2jZFhf3vL3PhBfmp3FwpD22pzyvWQP1uEuGtMxldcT47cOby0= 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 1741146803440869.1952492433169; Tue, 4 Mar 2025 19:53:23 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflV-0006b6-DN; Tue, 04 Mar 2025 22:49:49 -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 1tpfl7-0005DY-Fb for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:25 -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 1tpfl5-0006SM-Oz for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:24 -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-214-EEYZdi9_N9yyxcPMI5IWzQ-1; Tue, 04 Mar 2025 22:49:18 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 28F8C180036F; Wed, 5 Mar 2025 03:49:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 887CF1956095; Wed, 5 Mar 2025 03:49:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146562; 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=2QNFdU44Nnk/IStMvTW0EZuQ/J//zx6IVlDhhJASnvc=; b=D+kSbezu17TFMNIGx32Os23gQDplNCOW4aCs++YDgtZM03MjQzbC8XWUYZBcYeC7c6Swp3 KqxbALh9ufazatQ5xwKXeA+U5oqn7CEnzPyqVbmhBqTNnbTxF9pyFNwF32WI2dAVyNVcuM 0PYqjua/z6TahShyi2SH1ktxVt1egFw= X-MC-Unique: EEYZdi9_N9yyxcPMI5IWzQ-1 X-Mimecast-MFC-AGG-ID: EEYZdi9_N9yyxcPMI5IWzQ_1741146557 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 49/57] docs/qapidoc: add visit_member() method Date: Tue, 4 Mar 2025 22:45:58 -0500 Message-ID: <20250305034610.960147-50-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146805456019100 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 --- docs/sphinx/qapidoc.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6458790fe55..ed0269af27d 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -78,6 +78,16 @@ =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) -> None: self._curr_ent: Optional[QAPISchemaDefinition] =3D None self._result =3D StringList() @@ -88,6 +98,10 @@ def entity(self) -> QAPISchemaDefinition: 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: @@ -202,6 +216,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 and section.member + 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146773; cv=none; d=zohomail.com; s=zohoarc; b=JhXOMMgwldSl9lvP00RtJwn6lKXxoSAvbw1T7Oic9PW4rFk1b1UglzEAayB3X6NMS1XdQa8yWYBwAma2rsXl6AITJ7OCEgOUat/kzMZ0xbAkJhF/sLaBc5/P9+EHKohMF7s7SNQWt/xjjRtTP554o+dR+XqBqMfy3A1GrKFgAs0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146773; 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=HpqhHOOTiU3A8ngfVKgEqmqrwhJ8IiOiBgSyl9W96wU=; b=D4l2YqodkxZ9NvkHVCtS6yfN5qPA3oUJp9VSYDJgV4rLRComEsH2cMmVUX0gL01I7MEeDhBip/FDFMHmF89VMNpR21be06QTW1GBFuC2l5dIMKBT/0MHvLm4KrDAAusCZKnpsu7ehm/maa4FWqh+Uww1f7NHyjHyX+jPlUTGJvM= 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 174114677329346.08776107547328; Tue, 4 Mar 2025 19:52:53 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpfla-0007HN-Nm; Tue, 04 Mar 2025 22:49: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 1tpflP-0006DQ-KQ for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:43 -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 1tpflO-0006Vg-4R for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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-689-g0OUE05lPHaoXf8dtDHjEw-1; Tue, 04 Mar 2025 22:49:21 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 926B3180087D; Wed, 5 Mar 2025 03:49:20 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 86CB01956095; Wed, 5 Mar 2025 03:49:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146581; 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=HpqhHOOTiU3A8ngfVKgEqmqrwhJ8IiOiBgSyl9W96wU=; b=hFbBe6rJqsdTkTQozGDHbYiXsl71hcWI1mGn1VwvcbXoXlhVtERC5hdLJMOsJToDagyoxE 8sDwrucWK7LNa5edxNIXSKLG4zP/ePdZJJ79TcsETcJvn0skxqiwBSJU0Wz6aCWuTYNpt7 W1+3cjKX5hfom1gv9y5hjHrI/XoDeFQ= X-MC-Unique: g0OUE05lPHaoXf8dtDHjEw-1 X-Mimecast-MFC-AGG-ID: g0OUE05lPHaoXf8dtDHjEw_1741146560 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 50/57] docs/qapidoc: add visit_sections() method Date: Tue, 4 Mar 2025 22:45:59 -0500 Message-ID: <20250305034610.960147-51-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146773921019000 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 --- docs/sphinx/qapidoc.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index ed0269af27d..7308fa0a767 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -288,6 +288,31 @@ def preamble(self, ent: QAPISchemaDefinition) -> None: =20 self.ensure_blank_line() =20 + def visit_sections(self, ent: QAPISchemaDefinition) -> 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: + assert isinstance(section, QAPIDoc.ArgSection) + self.visit_member(section) + elif section.kind =3D=3D QAPIDoc.Kind.FEATURE: + assert isinstance(section, QAPIDoc.ArgSection) + 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146760; cv=none; d=zohomail.com; s=zohoarc; b=G8pMKutzAr9cXFM23fNvcM3yZHBoo5bsgn1aGRTcKXm+dm+s6c0prLrcBH2OhjEA/JVI1JcBT+DbEEvSqQn+9cU9oRbCpBSzl7R19ilbWVJ0Rxc4ii1AKaB7mWg66Uv8+EKo3p0TUS1osGrCllceIMPGRMmQH6UJW19xFA2r6yU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146760; 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=g4fd40egBu4gIs8kyZUy61ee8TmMN9/LsTce+Q6ojj8=; b=b5Q04ZY2Cpp21iVtOVCpimqDlL6C4FZJxDYDu5jsCd5Z0WD282qWO4eaHqh7Y5ldu2mpG8DY02E6U84afJG1sQdZFSf70dBBbGcP+SH52V86z99KljooH0aZ1rkfvKH48XNedCWvBKhESdsil1vbMTvWlrEOESEDpdRgeS+pA54= 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 1741146760841966.7210399491528; Tue, 4 Mar 2025 19:52:40 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflO-0005yX-4Y; Tue, 04 Mar 2025 22:49: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 1tpflJ-0005XV-Cr for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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 1tpflH-0006UU-La for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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-137--x4fTareMrKWS5nuEUHoOw-1; Tue, 04 Mar 2025 22:49:25 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 BCDBE1800262; Wed, 5 Mar 2025 03:49:24 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E28A91956095; Wed, 5 Mar 2025 03:49:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146574; 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=g4fd40egBu4gIs8kyZUy61ee8TmMN9/LsTce+Q6ojj8=; b=PJ4D2VxPnmbAIGjMfqojzVJkbhgqbHhnvgha5EK7vjOl3sXbqMVUKo1F1jSifOEoGfVfOX cvcrTHO27n0+zJnBBPKKjSCb8g7A4Oeyv/210KsF+fdwgaiHEScZF3mTuPucdvXMRano9I QLX31epvsMQb2zb8yBhi+eer+DdZ76Q= X-MC-Unique: -x4fTareMrKWS5nuEUHoOw-1 X-Mimecast-MFC-AGG-ID: -x4fTareMrKWS5nuEUHoOw_1741146564 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 51/57] docs/qapidoc: add visit_entity() Date: Tue, 4 Mar 2025 22:46:00 -0500 Message-ID: <20250305034610.960147-52-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146763341019100 Content-Type: text/plain; charset="utf-8" Finally, the core entry method for a qapi entity. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 7308fa0a767..fb2ad7492ae 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -78,6 +78,8 @@ =20 =20 class Transmogrifier: + # pylint: disable=3Dtoo-many-public-methods + # Field names used for different entity types: field_types =3D { "enum": "value", @@ -368,6 +370,25 @@ def visit_freeform(self, doc: QAPIDoc) -> None: self.add_lines(text, info) self.ensure_blank_line() =20 + def visit_entity(self, ent: QAPISchemaDefinition) -> None: + assert ent.info + + try: + self._curr_ent =3D ent + + # Squish structs and unions together into an "object" directiv= e. + meta =3D ent.meta + if meta in ("struct", "union"): + meta =3D "object" + + # This line gets credited to the start of the /definition/. + self.add_line(f".. qapi:{meta}:: {ent.name}", ent.info) + with self.indented(): + self.preamble(ent) + self.visit_sections(ent) + finally: + self._curr_ent =3D None + =20 class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146677; cv=none; d=zohomail.com; s=zohoarc; b=iZPiqdqcoUIVpZzhj3hVRcBS0XYOdnDHM9rkDjhXY37jg3HxbK3tf8zIjA6qooREUaY/squYvWbYVMtGBKkRxX40IwFeiOgu/2N/Hk6zu12H3mCYytD1niVnH2i/SWejTSDIveJ9nAlNbCm2rx12sK1mfdM/zh5WMY6F6YXdqss= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146677; 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=fpVyk2E5pAwiy0sgPsc+TmBNJh6lnIFuE7eKJHXQ3sQ=; b=Bh8FppxpR9aaa6UewFGtz1ENCC/8AjESMSycNaOSl7gOmoLewll9W4GeJ8k92G+KolD5pZuoFIv+0Br7Fao0Z8+Gy1NmuMYIVQQXrgSqEMyMuJNwrJ1KBuJc78gEKJLTpvnVUXrTR7Sh0a27DTjXV8ZRPPRllt11LaocC1pi67Y= 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 1741146677860650.6547084963426; Tue, 4 Mar 2025 19:51:17 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflY-0006uY-LZ; Tue, 04 Mar 2025 22:49: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 1tpflL-0005ii-EI for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:39 -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 1tpflJ-0006Ue-DT for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:39 -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-313-drpvy9BQPD-oN-EzBQunpQ-1; Tue, 04 Mar 2025 22:49:30 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 BEA1D180035D; Wed, 5 Mar 2025 03:49:28 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 380ED1956095; Wed, 5 Mar 2025 03:49:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146576; 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=fpVyk2E5pAwiy0sgPsc+TmBNJh6lnIFuE7eKJHXQ3sQ=; b=dpkQlm3hX+uL+PvudjxThyKu+Z1qagN/ELsN7BaSk+aQkgBnV8K9p9vbiT+D8MeBC3iLEd AnbVyoMn7kELIJNPKl0gwSPR+cfzwhNLS+6YnEZv7Nlk05tmLfPjhtd+ramyYG5HBGfR2L B0jKgHsgPJwMdH2HMppNenGV1vZCOr4= X-MC-Unique: drpvy9BQPD-oN-EzBQunpQ-1 X-Mimecast-MFC-AGG-ID: drpvy9BQPD-oN-EzBQunpQ_1741146568 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 52/57] docs/qapidoc: implement transmogrify() method Date: Tue, 4 Mar 2025 22:46:01 -0500 Message-ID: <20250305034610.960147-53-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146679849019000 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 --- docs/sphinx/qapidoc.py | 49 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index fb2ad7492ae..a4a0523d8ef 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. @@ -24,6 +25,8 @@ https://www.sphinx-doc.org/en/master/development/index.html """ =20 +# pylint: disable=3Dtoo-many-lines + from __future__ import annotations =20 from contextlib import contextmanager @@ -56,6 +59,7 @@ 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 @@ -76,6 +80,8 @@ =20 __version__ =3D "1.0" =20 +logger =3D logging.getLogger(__name__) + =20 class Transmogrifier: # pylint: disable=3Dtoo-many-public-methods @@ -95,6 +101,10 @@ def __init__(self) -> None: self._result =3D StringList() self.indent =3D 0 =20 + @property + def result(self) -> StringList: + return self._result + @property def entity(self) -> QAPISchemaDefinition: assert self._curr_ent is not None @@ -444,7 +454,43 @@ def new_serialno(self) -> str: return "qapidoc-%d" % env.new_serialno("qapidoc") =20 def transmogrify(self, schema: QAPISchema) -> nodes.Element: - raise NotImplementedError + logger.info("Transmogrifying QAPI to rST ...") + vis =3D Transmogrifier() + 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 isinstance(ent, QAPISchemaDefinition) + 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: QAPISchema) -> nodes.Element: vis =3D QAPISchemaGenRSTVisitor(self) @@ -578,6 +624,7 @@ def run(self) -> List[nodes.Node]: =20 def setup(app: Sphinx) -> ExtensionMetadata: """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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146799; cv=none; d=zohomail.com; s=zohoarc; b=IKTdF5KpCrGSwM953QyLFnByECVHXQK2xRiE6ePDlhwA+qJowbnIyFjnfRmk5Uc8Xz9lLfwdeFivuIj8AEZTezixZfJ+WZKiJzb90TMNy70AbTREGo3x8ePQmxrGxrgl6vku2Vi4AW91kBtItA1lsCutmYjiQEJNY6h3FYu7NyM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146799; 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=MP0Y28PtQu+hxOj9Oz8MbNi9pY63xIK2SXI57Fy0X4XSd5GR+xpkDJRrnLcU0LInR3wo88spPd8cXTfmvBHF7uKaZTNaCHnAsHdWgY0IGtNTDSlcA0fyllfcCBGX5w6Zi8Kfc58tukAzCAhS6inGaTloL/myGyOBIYgZqVShxyY= 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 1741146799620957.1747602131475; Tue, 4 Mar 2025 19:53:19 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflW-0006gA-7v; Tue, 04 Mar 2025 22:49:50 -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 1tpflM-0005tD-HV for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:40 -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 1tpflK-0006Ux-MW for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:40 -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-322-p5QP6MnJOwaOB_KSIW3sEQ-1; Tue, 04 Mar 2025 22:49:32 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 AE1E119039CE; Wed, 5 Mar 2025 03:49:31 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 36F4A1956095; Wed, 5 Mar 2025 03:49:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146578; 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=SkW5f8wCkpQQfOGjrGIgAHzQfNaw2D61sbgla5bX8QHl17083Xz72Bg5BfTS3eIH0NVrPc tOlH7g5biuIH04hdvu/+wavw/MqRbKy6lBUGmgh2CN7S/c+9f4Bdfm4ZxUTL63Zwvtqxjd r2YfWPmJjagfRmDuiSKYEUcd+M4sCtY= X-MC-Unique: p5QP6MnJOwaOB_KSIW3sEQ-1 X-Mimecast-MFC-AGG-ID: p5QP6MnJOwaOB_KSIW3sEQ_1741146571 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 53/57] docs: disambiguate cross-references Date: Tue, 4 Mar 2025 22:46:02 -0500 Message-ID: <20250305034610.960147-54-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146799953019000 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 --- 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146723; cv=none; d=zohomail.com; s=zohoarc; b=ZD865dmXZBdHD3WjuQFUYdwX5AFqQC/EaYDIcG/5eP9iGYtAYVXHKeP2RUJJC9g5ci4j30z0O1ATfmFnufonpf1npY/PEq9JqSgw62PlrhkgiJIw+m0Fv2H1JB8awVCowkzePsKYMy0zpBOpkzzwFKYjJycxLST6TrE7M/Ypp1M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146723; 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=e5urStQP63jkqPMNX2eWKJXzq7q9kxq6QAKJEtebhcU=; b=aOiAWrMTM/Pxi5CBLS/houMzTquPbygB45YDqpZTBd4ew3DpynTHsPQF0t+MYCgxBP1E86sR8HtyBXRG1Q8b9jiqTNwr9/bCkywL1wpplimDb0r0b/+sfF5jdyiW5NaxoWcNTvhmDEGD/GIhFI499CDOoqMQqnv6fAIriO/lYEI= 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 174114672351936.74575104127064; Tue, 4 Mar 2025 19:52:03 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflQ-0006Fk-HI; Tue, 04 Mar 2025 22:49:44 -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 1tpflM-0005uF-Pq for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:40 -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 1tpflK-0006Uz-NY for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:40 -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-340-tD9_x6NmPsWWh5WBswH_og-1; Tue, 04 Mar 2025 22:49:36 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 A309119560BC; Wed, 5 Mar 2025 03:49:35 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 43E371956095; Wed, 5 Mar 2025 03:49:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146578; 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=e5urStQP63jkqPMNX2eWKJXzq7q9kxq6QAKJEtebhcU=; b=JLYqARfcY+rbx/xdClcQoYYbaVi+1lfw2LXkV+w+nO6DlWNjkHAhuowXmSx0Fn9IddlnyD qIsRFlM5gMcL+W3Wt49PGP3dFa7gkNUYfQd41gRlFXZdNceOv/VXjq72JRRxY2grvwZ/Ec TCYAAoNjX458uCyF/hOKCu2rXREQYsQ= X-MC-Unique: tD9_x6NmPsWWh5WBswH_og-1 X-Mimecast-MFC-AGG-ID: tD9_x6NmPsWWh5WBswH_og_1741146575 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 54/57] docs/qapidoc: add transmogrifier test document Date: Tue, 4 Mar 2025 22:46:03 -0500 Message-ID: <20250305034610.960147-55-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146725181019100 Content-Type: text/plain; charset="utf-8" This is just a test document that demonstrates the new qapi-domain doc generator. Note that this test document uses a nesting depth of 2 for the TOC unlike the existing QMP's reference nesting depth of 3. It's arbitrary and can be changed to suit taste, it has nothing to do with the new domain itself. Signed-off-by: John Snow --- 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 Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146743; cv=none; d=zohomail.com; s=zohoarc; b=WQcxjMjZm6IZ7Y3/ij9a7ep34up/9pUDjUYkEtwYJAbDCizplNIYQie6tkTG3vRrt4bnCPIwBClyFhefw6wPWRds2JAS9mjy/MQ+06PoaYIqUYud0lDuCFeV+2y1BhdbSoC5EdHQ7Gvri0TLpJwyQXs5nYgthub2iP1tZ5NGW50= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146743; 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=ehMoX4yOdluOsSo02Vsb9GWGFWw90UeHEItwU/Pq3pQ=; b=VtXmtTU1GpzdR3BuyLiWYzmcWv9dzHALPS1eL74bnGOLtwiBmjftmChBSqz5CH3eFhOPTRFkcu0oGXa2c5zL7qWoKHhvVUQb32P4SWIlAaiwMIhQ55Q+p+DYeH0tQH2rPJEL2WhPKNofzp/6q22spmOE/B6YqbTuDWQg2yS8ohM= 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 1741146743607502.4213722369575; Tue, 4 Mar 2025 19:52:23 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflc-0007aI-Uu; Tue, 04 Mar 2025 22:49: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 1tpflQ-0006JK-Fw for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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 1tpflO-0006W1-Rz for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:44 -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-657-ZBbHJJQLNKqepBeN79X6yQ-1; Tue, 04 Mar 2025 22:49:40 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 AB5BD1918160; Wed, 5 Mar 2025 03:49:39 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 468441956095; Wed, 5 Mar 2025 03:49:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146582; 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=ehMoX4yOdluOsSo02Vsb9GWGFWw90UeHEItwU/Pq3pQ=; b=c+LREFCKpPoenqSKTl25ctpFFeWNNvoci5hkK6KmpG6hUZLsH5L4ZPV8PONEBJL5vzsjqI 9lzWDeqkhIBCeX263G1HcPGxIKMcHYnsmYbHeXoQHj1HwCVfFicTZtM5/IOQC1OLBOmhvr Tv4Tlptmm4J8rdP06Cw/gC+aK7vrqWg= X-MC-Unique: ZBbHJJQLNKqepBeN79X6yQ-1 X-Mimecast-MFC-AGG-ID: ZBbHJJQLNKqepBeN79X6yQ_1741146579 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 55/57] docs/qapidoc: process @foo into ``foo`` Date: Tue, 4 Mar 2025 22:46:04 -0500 Message-ID: <20250305034610.960147-56-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146745295019100 Content-Type: text/plain; charset="utf-8" Add support for the special QAPI doc syntax to process @references as ``preformatted text``. At the moment, there are no actual cross-references for individual members, so there is nothing to link against. For now, process it identically to how we did in the old qapidoc system. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index a4a0523d8ef..c84fff95697 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -305,6 +305,9 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> = None: =20 # Add sections *in the order they are documented*: for section in sections: + # @var is translated to ``var``: + section.text =3D re.sub(r"@([\w-]+)", r"``\1``", section.text) + if section.kind =3D=3D QAPIDoc.Kind.PLAIN: self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146759; cv=none; d=zohomail.com; s=zohoarc; b=VmuX0VU9/huvIkR31dCavZuCfknwoUMOlgik3dvG+i4a4DC7KTtWLfI8x6qqhOBNB5Vzoo0GXMDdjluGFDjOksKRGPoTu6DfpWIEWKdkjaLceaLFkXMR43UFEet0W/8qqZYCNV0iU8sU+Dc9KSYh65YtFnxghZVtLIpzyWecR3U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146759; 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=X4AooeAWCy0CWv4A/CKNkxtyjyua6rWbSkQB3v9ezrc=; b=HlIq9yboZ6POIN7qwR1HAT2LhHk8rgoCYleJ7+XsO33twb66DJok92TUYE199FpaXR+qBxM2cuZCpJ1rdsBzirNd5cTtVynoIRnceUg1yEign73HDQHm87sQ37jC7tDgGWTZvwRYdehXH9heLQsvTnEFnAlGG0RJPI69s1d7VPg= 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 1741146759544929.9519148232667; Tue, 4 Mar 2025 19:52:39 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflh-0007y1-38; Tue, 04 Mar 2025 22:50:01 -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 1tpflc-0007bp-Lj for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49: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 1tpfla-0006XV-UA for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:49:56 -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-226-25a5tXs5PaKADp3RrYEDZw-1; Tue, 04 Mar 2025 22:49:44 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 E2CFE1954234; Wed, 5 Mar 2025 03:49:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 45BA21956095; Wed, 5 Mar 2025 03:49:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146594; 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=X4AooeAWCy0CWv4A/CKNkxtyjyua6rWbSkQB3v9ezrc=; b=AgToj01IgeUr8kn/tnfKx65jPCP08oJexABWaguDWCjCkvYKHnqQv7zacliAJzRkuzrdUs I5BWn7tr2W79koMJ9rbHn23YfaOH165dvbcHmmsI27+fOj1wU3Ha5t6MEiNc3eNWlQGK3+ 6v/sAkCrwnQ7WVFS7fBja7PvUGn9nY0= X-MC-Unique: 25a5tXs5PaKADp3RrYEDZw-1 X-Mimecast-MFC-AGG-ID: 25a5tXs5PaKADp3RrYEDZw_1741146583 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 56/57] docs/qapidoc: add intermediate output debugger Date: Tue, 4 Mar 2025 22:46:05 -0500 Message-ID: <20250305034610.960147-57-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: 1741146761374019100 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 --- 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 c84fff95697..511bab1592c 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -37,7 +37,7 @@ from typing import TYPE_CHECKING =20 from docutils import nodes -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import directives from docutils.statemachine import StringList from qapi.error import QAPIError from qapi.parser import QAPIDoc @@ -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 @@ -422,7 +422,7 @@ def visit_module(self, name: str) -> None: super().visit_module(name) =20 =20 -class NestedDirective(Directive): +class NestedDirective(SphinxDirective): def run(self) -> Sequence[nodes.Node]: raise NotImplementedError =20 @@ -491,10 +491,43 @@ def transmogrify(self, schema: QAPISchema) -> nodes.E= lement: 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: StringList, filename: str) -> No= ne: + 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) + srcpath =3D Path(src).resolve() + srcpath =3D srcpath.relative_to(srctree) + + lcol =3D f"{srcpath}:{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: QAPISchema) -> nodes.Element: vis =3D QAPISchemaGenRSTVisitor(self) vis.visit_begin(schema) --=20 2.48.1 From nobody Wed Apr 2 13:05:54 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741146791; cv=none; d=zohomail.com; s=zohoarc; b=N3eopRbl9Qb+JLfaMSLZFXsjm63XaqqjNnoHJv0j8YqYcxQ4Viimzyci1adXBg/jdXOMmpn5afuywbKE25UjkjWcgrk2FRJ3dKOm7ipSYuVmJ6BAg6DwXm4ZFTkDGMJlGFwENMf2EvRZ9tv4VJQp6KCgTwSO0FawrG0pH/mNDwg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741146791; 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=5cbnCGow0JjCIf7HC6HYaOG957rm1yw3vsP9/lQoPGY=; b=ElHzZbzsUG9otVt7nstUwvm3rLKYUQRf+0UIRJyH2X5yCq3boeMC+pX898bXvjZBSc4sTI1XOpcdMAgLLzmZicEcuW8CjiSfsItIIHiolkbr/44POGlr0CTyh/QrTfjCo1IVu1Qn+QuRAFmbOaWwNz1PNvBcb3CDlKT2zRM0zz0= 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 1741146791332577.6305624403037; Tue, 4 Mar 2025 19:53:11 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tpflp-00008x-J4; Tue, 04 Mar 2025 22:50:09 -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 1tpflk-0008LD-9I for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:50:05 -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 1tpflh-0006Yi-V1 for qemu-devel@nongnu.org; Tue, 04 Mar 2025 22:50:03 -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-576-ggdEtmyAMPy_eQG-3Sf1eg-1; Tue, 04 Mar 2025 22:49:48 -0500 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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 2B4B41800346; Wed, 5 Mar 2025 03:49:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.45]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A284A1956095; Wed, 5 Mar 2025 03:49:43 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741146601; 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=5cbnCGow0JjCIf7HC6HYaOG957rm1yw3vsP9/lQoPGY=; b=TSWawMycXYNQRNhN2nuAMLZqdizZlwbEc1C8lpitIbbatNmDaOfjTsbNYrRmJiI7VauAms 1ofk44v8tuKdFbPVHlMSUzlsNlQBr4VnMlA5aicHrY/XXYWVkesdh7gq8mPgFEesXHHUy1 NlAV79XGKOv3MiNRNZ0P59tod0UX9Ys= X-MC-Unique: ggdEtmyAMPy_eQG-3Sf1eg-1 X-Mimecast-MFC-AGG-ID: ggdEtmyAMPy_eQG-3Sf1eg_1741146587 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , John Snow Subject: [PATCH 57/57] docs/qapidoc: Add "the members of" pointers Date: Tue, 4 Mar 2025 22:46:06 -0500 Message-ID: <20250305034610.960147-58-jsnow@redhat.com> In-Reply-To: <20250305034610.960147-1-jsnow@redhat.com> References: <20250305034610.960147-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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: -3 X-Spam_score: -0.4 X-Spam_bar: / X-Spam_report: (-0.4 / 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, URIBL_CSS_A=0.1, URIBL_SBL=1.623 autolearn=no 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: 1741146793516019100 Content-Type: text/plain; charset="utf-8" Add "the members of ..." pointers to Members and Arguments lists where appropriate, with clickable cross-references - so it's a slight improvement over the old system :) This patch is meant to be a temporary solution until we can review and merge the inliner. The implementation of this patch is a little bit of a hack: Sphinx is not designed to allow you to mix fields of different "type"; i.e. mixing member descriptions and free-form text under the same heading. To accomplish this with a minimum of hackery, we technically document a "dummy field" and then just strip off the documentation for that dummy field in a post-processing step. We use the "q_dummy" variable for this purpose, then strip it back out before final processing. If this processing step should fail, you'll see warnings for a bad cross-reference. (So if you don't see any, it must be working!) Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 22 +++++++++++++-- docs/sphinx/qapidoc.py | 58 +++++++++++++++++++++++++++++++++++++- 2 files changed, 77 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 077ab7ae47a..a3c89a85f44 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -165,6 +165,24 @@ def since_validator(param: str) -> str: return param =20 =20 +class SpecialTypedField(CompatTypedField): + def make_field(self, *args: Any, **kwargs: Any) -> nodes.field: + ret =3D super().make_field(*args, **kwargs) + + # Look for the characteristic " -- " text node that Sphinx + # inserts for each TypedField entry ... + for node in ret.traverse(lambda n: str(n) =3D=3D " -- "): + par =3D node.parent + if par.children[0].astext() !=3D "q_dummy": + continue + + # If the first node's text is q_dummy, this is a dummy + # field we want to strip down to just its contents. + del par.children[:-1] + + return ret + + class QAPIObject(ParserFix): """ Description of a generic QAPI object. @@ -451,7 +469,7 @@ class QAPICommand(QAPIObject): doc_field_types.extend( [ # :arg TypeName ArgName: descr - CompatTypedField( + SpecialTypedField( "argument", label=3D_("Arguments"), names=3D("arg",), @@ -519,7 +537,7 @@ class QAPIObjectWithMembers(QAPIObject): doc_field_types.extend( [ # :member type name: descr - CompatTypedField( + SpecialTypedField( "member", label=3D_("Members"), names=3D("memb",), diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 511bab1592c..daddb709628 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -47,8 +47,10 @@ QAPISchemaCommand, QAPISchemaDefinition, QAPISchemaEnumMember, + QAPISchemaEvent, QAPISchemaFeature, QAPISchemaMember, + QAPISchemaObjectType, QAPISchemaObjectTypeMember, QAPISchemaType, QAPISchemaVisitor, @@ -300,11 +302,61 @@ def preamble(self, ent: QAPISchemaDefinition) -> None: =20 self.ensure_blank_line() =20 + def _insert_member_pointer(self, ent: QAPISchemaDefinition) -> None: + + def _get_target( + ent: QAPISchemaDefinition, + ) -> Optional[QAPISchemaDefinition]: + if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)): + return ent.arg_type + if isinstance(ent, QAPISchemaObjectType): + return ent.base + return None + + target =3D _get_target(ent) + if target is not None and not target.is_implicit(): + assert ent.info + self.add_field( + self.member_field_type, + "q_dummy", + f"The members of :qapi:type:`{target.name}`.", + ent.info, + "q_dummy", + ) + + if isinstance(ent, QAPISchemaObjectType) and ent.branches is not N= one: + for variant in ent.branches.variants: + if variant.type.name =3D=3D "q_empty": + continue + assert ent.info + self.add_field( + self.member_field_type, + "q_dummy", + f" When ``{ent.branches.tag_member.name}`` is " + f"``{variant.name}``; " + f"The members of :qapi:type:`{variant.type.name}`.", + ent.info, + "q_dummy", + ) + def visit_sections(self, ent: QAPISchemaDefinition) -> None: sections =3D ent.doc.all_sections if ent.doc else [] =20 + # Determine the index location at which we should generate + # documentation for "The members of ..." pointers. This should + # go at the end of the members section(s) if any. Note that + # index 0 is assumed to be a plain intro section, even if it is + # empty; and that a members section if present will always + # immediately follow the opening PLAIN section. + gen_index =3D 1 + if len(sections) > 1: + while sections[gen_index].kind =3D=3D QAPIDoc.Kind.MEMBER: + gen_index +=3D 1 + if gen_index >=3D len(sections): + break + # Add sections *in the order they are documented*: - for section in sections: + for i, section in enumerate(sections): # @var is translated to ``var``: section.text =3D re.sub(r"@([\w-]+)", r"``\1``", section.text) =20 @@ -326,6 +378,10 @@ def visit_sections(self, ent: QAPISchemaDefinition) ->= None: else: assert False =20 + # Generate "The members of ..." entries if necessary: + if i =3D=3D gen_index - 1: + self._insert_member_pointer(ent) + self.ensure_blank_line() =20 # Transmogrification core methods --=20 2.48.1