From patchwork Tue Mar 11 03:42:56 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 14011029 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 34C5EC28B2E for ; Tue, 11 Mar 2025 03:52:06 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trqaH-0003i6-4H; Mon, 10 Mar 2025 23:47:16 -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 1trqZt-0000bi-Ar for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:46:49 -0400 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 1trqZd-0002px-KN for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:46:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741664793; 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=/XsONImegYQ6OtAUDrUF4BZPL3TvhnJW4mB6Wtf5gho=; b=jNqRB2xRs5jcw3bfwLqDzAvoDGzUoCm2lPBEw/+J+SN7sH570nH0XXb0kLpCgQYx/eUDM5 h13GxdIlcv1gy/uAULI23bNMZOBWeLh5q44/vm1r5aCeWPUdOIG9xTngGBBzu+LAI1kuy8 jD7pemCVoj9R15SYqsqQU7c3ugIPMSw= 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-46-wOl32DNrNHmuYpVWLCXoUQ-1; Mon, 10 Mar 2025 23:46:29 -0400 X-MC-Unique: wOl32DNrNHmuYpVWLCXoUQ-1 X-Mimecast-MFC-AGG-ID: wOl32DNrNHmuYpVWLCXoUQ_1741664788 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9B55719560AB; Tue, 11 Mar 2025 03:46:28 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 5FD051800366; Tue, 11 Mar 2025 03:46:25 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , John Snow , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Eric Blake , Michael Roth , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Markus Armbruster Subject: [PATCH v3 58/63] docs/qapidoc: generate entries for undocumented members Date: Mon, 10 Mar 2025 23:42:56 -0400 Message-ID: <20250311034303.75779-59-jsnow@redhat.com> In-Reply-To: <20250311034303.75779-1-jsnow@redhat.com> References: <20250311034303.75779-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Presently, we never have any empty text entries for members. The next patch will explicitly generate such sections, so enable support for it in advance. The parser will generate placeholder sections to indicate undocumented members, but it's the qapidoc generator that's responsible for deciding what to do with that stub section. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 7c5a08958d5..604ab109a19 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -233,11 +233,12 @@ def visit_member(self, section: QAPIDoc.ArgSection) -> None: # TODO: features for members (documented at entity-level, # but sometimes defined per-member. Should we add such # information to member descriptions when we can?) - assert section.text and section.member + assert section.member self.generate_field( self.member_field_type, section.member, - section.text, + # TODO drop fallbacks when undocumented members are outlawed + section.text if section.text else "Not Documented.", section.info, )