From patchwork Fri Dec 13 01:12:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13906248 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 5F6ABE77180 for ; Fri, 13 Dec 2024 01:14:58 +0000 (UTC) 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 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= 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 X-MC-Unique: LvusOLgfNxi7H7kPVEnUTA-1 X-Mimecast-MFC-AGG-ID: LvusOLgfNxi7H7kPVEnUTA 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) From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Markus Armbruster , Peter Maydell , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , 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 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org ``: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 @@ -261,6 +261,13 @@ class QAPICommand(QAPIObject): names=("arg",), can_collapse=False, ), + # :error: descr + Field( + "error", + label=_("Errors"), + names=("error", "errors"), + has_arg=False, + ), ] )