From nobody Mon Nov 25 11:35:11 2024 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=1715724222; cv=none; d=zohomail.com; s=zohoarc; b=R+PDebvfs/2tKMde1LBMgqZfW10ELu6xzfixgL7CsFCfB2x1ggAadrd1pLhkwilKgxcnm014Ak89h/EYCu51Fe+JlPEdKbgFZCa2/03DeqRY73Q8Vu2FyEVBY/u+VcR9OVCr50C1ngRZj4i+QqhyPyjSnhpQErcaqSA8DqT7xC4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724222; 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=jfg570U3FRLJ35JfLCL81gkmcp7TkhTnNgfcr0FLQCE=; b=mGBTLFRwBVekkSlFOpCLm8qgzR6+GfwTk+xtrTxh0KXFyGOCKz0RTRgh5DV19goZvKIIZ+VWxK9F6EUlnqVcemDaGJIwXFxIf3zKZTq5zK1az/3H7PB8j5J2dgXydd8z9EATg+eZi4E68uCo4vv76H24uCKsdclcRQXvMT2ArUc= 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 1715724222706882.9059812665272; Tue, 14 May 2024 15:03:42 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AQ-0005kN-8y; Tue, 14 May 2024 17:58:38 -0400 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 1s70AO-0005iK-0C for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:36 -0400 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 1s70AG-0008W3-1l for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-571-8cdUitqFMY-lQQ2HJ4yOaw-1; Tue, 14 May 2024 17:58:21 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5AAB01C031AC; Tue, 14 May 2024 21:58:20 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7179C6BC0; Tue, 14 May 2024 21:58:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723907; 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=jfg570U3FRLJ35JfLCL81gkmcp7TkhTnNgfcr0FLQCE=; b=Hvei26IP+pVxs6ZPE1LKMSujskT5Ft9ygDcAPMwSkNGIQPwYor/ERUB0N+AgYfCcqe2Xcn yIQHX8qYNm2f6qb/QRMNqYqA7UL9KX3wrIi1SCLsZC0IW+YX1bTVrFO7P8A7f5umpy/0YR vfoUtczpNIa2H8g/hnrSXCoAPk/7nfE= X-MC-Unique: 8cdUitqFMY-lQQ2HJ4yOaw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 11/20] qapi/schema: add doc_visible property to QAPISchemaDefinition Date: Tue, 14 May 2024 17:57:30 -0400 Message-ID: <20240514215740.940155-12-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, 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_H4=0.001, RCVD_IN_MSPIKE_WL=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: 1715724223526100003 Content-Type: text/plain; charset="utf-8" The intent here is to mark only certain definitions as visible in the end-user docs. All commands and events are inherently visible. Everything else is visible only if it is a member (or a branch member) of a type that is visible, or if it is named as a return type for a command. Notably, this excludes arg_type for commands and events, and any base_types specified for structures/unions. Those objects may still be marked visible if they are named as members from a visible type. This does not necessarily match the data revealed by introspection: in this case, we want anything that we are cross-referencing in generated documentation to be available to target. Some internal and built-in types may be marked visible with this approach, but if they do not have a documentation block, they'll be skipped by the generator anyway. This includes array types and built-in primitives which do not get their own documentation objects. This information is not yet used by qapidoc, which continues to render documentation exactly as it has. This information will be used by the new qapidoc (the "transmogrifier"), to be introduced later. The new generator verifies that all of the objects that should be rendered *are* by failing if any cross-references are missing, verifying everything is in place. Signed-off-by: John Snow --- scripts/qapi/schema.py | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index e15e64ea8cb..6025b4e9354 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -131,6 +131,7 @@ def __init__( self.doc =3D doc self._ifcond =3D ifcond or QAPISchemaIfCond() self.features =3D features or [] + self.doc_visible =3D False =20 def __repr__(self) -> str: return "<%s:%s at 0x%x>" % (type(self).__name__, self.name, @@ -146,6 +147,10 @@ def check(self, schema: QAPISchema) -> None: for f in self.features: f.check_clash(self.info, seen) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + if mark_self: + self.doc_visible =3D True + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -483,6 +488,10 @@ def check(self, schema: QAPISchema) -> None: self.info.defn_meta if self.info else None) assert not isinstance(self.element_type, QAPISchemaArrayType) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + self.element_type.mark_visible() + def set_module(self, schema: QAPISchema) -> None: self._set_module(schema, self.element_type.info) =20 @@ -607,6 +616,17 @@ def connect_doc(self, doc: Optional[QAPIDoc] =3D None)= -> None: for m in self.local_members: m.connect_doc(doc) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + # Mark this object and its members as visible in the user-facing d= ocs. + if self.doc_visible: + return + + super().mark_visible(mark_self) + for m in self.members: + m.type.mark_visible() + for var in self.branches or []: + var.type.mark_visible(False) + def is_implicit(self) -> bool: # See QAPISchema._make_implicit_object_type(), as well as # _def_predefineds() @@ -698,6 +718,11 @@ def check(self, schema: QAPISchema) -> None: % (v.describe(self.info), types_seen[qt])) types_seen[qt] =3D v.name =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + for var in self.alternatives: + var.type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1056,6 +1081,13 @@ def check(self, schema: QAPISchema) -> None: "command's 'returns' cannot take %s" % self.ret_type.describe()) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + if self.ret_type: + self.ret_type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1112,6 +1144,11 @@ def check(self, schema: QAPISchema) -> None: self.info, "conditional event arguments require 'boxed': true") =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1488,6 +1525,9 @@ def check(self) -> None: ent.set_module(self) for doc in self.docs: doc.check() + for ent in self._entity_list: + if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)): + ent.mark_visible() =20 def visit(self, visitor: QAPISchemaVisitor) -> None: visitor.visit_begin(self) --=20 2.44.0