From nobody Tue Feb 10 05:44:44 2026 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=1683619630; cv=none; d=zohomail.com; s=zohoarc; b=NNGfQySYRptQ9YfqIFk8crydsOupejdROHimA51wuuI19rmb/BNTGfGsURrSonSjwWTrIosCBI029QOf+9Rik0r+kEpXKCuaekl58o9LQ+q1+Z+suK2gkrb5ITWPAWggV4y6Ys+EXy2t5iA6ISbgTqPPdkuAyg4fJbUHpgCeHIs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1683619630; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=0Ymub+txARZ2PWH5OgCKZTaI9UggN4L92uTgTN01hxc=; b=Fkopcmg1J/j1H1ljePrJ0yxIQtku5Vc2QPwHLrVb9zXy3u2/2vhP0wgD3VblhkSWRdKRk4oPhmT2vSwyWUBY6CEVj4lTX9q2EGckwc4H7wGuEzij6/zzkwszrDuYW6BUhj/yCCQHWNw6/MNF1HOA/bq+TNvQZyiixNbVcDEd3jc= 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 1683619630177730.9458661669202; Tue, 9 May 2023 01:07:10 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pwIGu-00006h-K4; Tue, 09 May 2023 04:00:32 -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 1pwIGm-0008UO-1E for qemu-devel@nongnu.org; Tue, 09 May 2023 04:00:27 -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 1pwIGj-0008UV-Vd for qemu-devel@nongnu.org; Tue, 09 May 2023 04:00:23 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-324-Y2COXLq9PwGZ-9oVRgXbig-1; Tue, 09 May 2023 04:00:18 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D3C5F884629; Tue, 9 May 2023 08:00:17 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id AD94E2166B29; Tue, 9 May 2023 08:00:17 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 2B38021E6681; Tue, 9 May 2023 10:00:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1683619221; 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=0Ymub+txARZ2PWH5OgCKZTaI9UggN4L92uTgTN01hxc=; b=hJl2l6Od+Zl5GQ81RYEtU3OMJUnYP8b6x0c68ZUCn4ZHRe3ZpihXpo12m0z4UABhf4P/dd yHSBJ6d0bE/78/Q/KQldvxbygUJXHnhny1Gc+YRi4VlD5BpEeffU6dpkJTpGWGA5z1zw81 mk82yMobQ2ceQsWma0IisRXIpUPU2zA= X-MC-Unique: Y2COXLq9PwGZ-9oVRgXbig-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: richard.henderson@linaro.org, Ani Sinha , Juan Quintela Subject: [PULL 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals Date: Tue, 9 May 2023 10:00:00 +0200 Message-Id: <20230509080011.3231661-7-armbru@redhat.com> In-Reply-To: <20230509080011.3231661-1-armbru@redhat.com> References: <20230509080011.3231661-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.6 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=armbru@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, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-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: 1683619631565100001 Content-Type: text/plain; charset="utf-8" QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual". The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals. This elides the following TODOs: * SchemaInfoCommand # TODO: @success-response (currently irrelevant, because it's QGA, not QM= P) This is a note to developers adding introspection to the guest agent. It makes no sense to users. * @query-hotpluggable-cpus # TODO: Better documentation; currently there is none. This is a reminder for developers. It doesn't help users. * @device_add # TODO: This command effectively bypasses QAPI completely due to its # "additional arguments" business. It shouldn't have been added to # the schema in this form. It should be qapified properly, or # replaced by a properly qapified command. Likewise. Eliding them is an improvement. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-7-armbru@redhat.com> Reviewed-by: Ani Sinha Reviewed-by: Juan Quintela --- docs/devel/qapi-code-gen.rst | 5 +++-- docs/sphinx/qapidoc.py | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ff7b74bdb2..6386b58881 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release tha= t introduced the definition. =20 An "Example" or "Examples" section is automatically rendered entirely -as literal fixed-width text. In other sections, the text is -formatted, and rST markup can be used. +as literal fixed-width text. "TODO" sections are not rendered at all +(they are for developers, not users of QMP). In other sections, the +text is formatted, and rST markup can be used. =20 For example:: =20 diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d791b59492..8f3b9997a1 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist =3D [] for section in doc.sections: + if section.name and section.name =3D=3D 'TODO': + # Hide TODO: sections + continue snode =3D self._make_section(section.name) if section.name and section.name.startswith('Example'): snode +=3D self._nodes_for_example(section.text) --=20 2.39.2