From nobody Wed Jan 29 00:08:14 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=1734052498; cv=none; d=zohomail.com; s=zohoarc; b=mCxuJ+Id6gssH7vrcXwYRD2OTy9aHRMrdLkelftR6Ug7uQfOpFZhR7oM5+Y9CbepA4fXNlu0AzflbRvhQI2dbcUPTwMNfG13AS04zy7wIlz8BW/iPRx+OQ0wJ6vKeCfaRD36qdGJJGj28e6Jfj3YhW3FUelL73m3qfD4gjz6v6A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1734052498; 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=QPdepso8xSmP8leeknmWo8NzlmVarvknHnZdmjkDCPM=; b=MULijasF639b5tHDYN8h/WtI3vTDPe4z8Hww2AF6Vnqt/g7t5gqwqyVo/JVt4N+12Jm1wA8O1ZYdFWUgwj59fNmxao+NPoeK9UndYJfPwp9cm4xb4BZ8grCf3jakYJEh8xHjnU7+BNzcIzy0BDfoahQ2onJNfYiR+AR7WX0dk5o= 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 1734052498586517.7892291642265; Thu, 12 Dec 2024 17:14:58 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tLuGF-0005zQ-Tg; Thu, 12 Dec 2024 20:14:31 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tLuGA-0005th-Q8 for qemu-devel@nongnu.org; Thu, 12 Dec 2024 20:14:27 -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 1tLuG7-0000ef-TJ for qemu-devel@nongnu.org; Thu, 12 Dec 2024 20:14:26 -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-329-LvusOLgfNxi7H7kPVEnUTA-1; Thu, 12 Dec 2024 20:14:16 -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 93E5E195604F; Fri, 13 Dec 2024 01:14:15 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.88.22]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 58D931956086; Fri, 13 Dec 2024 01:14:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1734052463; 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=QPdepso8xSmP8leeknmWo8NzlmVarvknHnZdmjkDCPM=; b=d5Xzlm2ISEyg+UcKxQdSLbaDBlV4RPrPIuvD6aQa0vnadDbo8yhVc71vbvbcqayOD/kNFa YuZ2EN6IoRVCmCq5n/zVI5fm1CsIH6bBiQFg0ibBiN1IWBPijvb1+F05YKuioRCDGfDcBW ZPEfh6CGbZe1VQGpH4Cw2k6MvRE9Kr0= X-MC-Unique: LvusOLgfNxi7H7kPVEnUTA-1 X-Mimecast-MFC-AGG-ID: LvusOLgfNxi7H7kPVEnUTA From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Markus Armbruster , Peter Maydell , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Victor Toso de Carvalho , Paolo Bonzini , John Snow Subject: [RFC PATCH v2 15/35] docs/qapi-domain: add "Errors:" field lists Date: Thu, 12 Dec 2024 20:12:44 -0500 Message-ID: <20241213011307.2942030-16-jsnow@redhat.com> In-Reply-To: <20241213011307.2942030-1-jsnow@redhat.com> References: <20241213011307.2942030-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: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.496, 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: 1734052499330116600 Content-Type: text/plain; charset="utf-8" ``:error: descr`` can now be used to document error conditions, naming the type of error object and a description of when the error is surfaced. Like the previous Arguments patch, this patch does not apply any special QAPI syntax highlighting or cross-referencing for the types, but this can be adjusted in the future if desired. (At present, I have no commits that add such highlighting. Sphinx also does not appear to support Grouped fields with optional (or no) parameters, so the ability to exclude error types is currently not supported. If you omit the type, Sphinx treats it as a regular field list and doesn't apply the special Grouping postprocessing to it.) Signed-off-by: John Snow qapi-domain fixup - Error field 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 9b83262a0c6..4bfc82aafdf 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -34,7 +34,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 @@ -261,6 +261,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.47.0