From nobody Sun Nov 24 07:04:10 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=1724754998; cv=none; d=zohomail.com; s=zohoarc; b=S+AQcFLWoa0e1byzXymEMX+bq7zpjMjaZZm2s4lgxEmYwc7ZJshbQed2YfrRANZ/DqvvLnMEj4REPy1bZljNQ3FvHkwk6A6LMaBKDzmPEQ4wdCHG9PBer255V7p06lGHly50yoGHeXPzdRakkmha0KDShrq/6f092dlwlV//tXU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1724754998; h=Content-Type: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=i4Q8o0IG0jTVd7vOErL8HdXdFcv0ZdMf445XvAP4iWo=; b=HtLQ4CGRQu+yM7IyqfP/XT+AvOkyAkfMZbBa87qmgIavJ0mTmefl3DkNjZlm71Hi79HGIG/VKFs3NkhctTRLBygEVSSZ/BSjitKZ9r+3zoi/KkHaO+KZUibmi4rszTnvc0o7Y5Di3W2zNO9l1yWrrQi0nOCWDWYTbyb8Hba8vco= 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 1724754998689241.02419084715245; Tue, 27 Aug 2024 03:36:38 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sitYC-000504-93; Tue, 27 Aug 2024 06:35:48 -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 1sitY7-0004ym-VT for qemu-devel@nongnu.org; Tue, 27 Aug 2024 06:35:44 -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 1sitY6-0004Yf-0I for qemu-devel@nongnu.org; Tue, 27 Aug 2024 06:35:43 -0400 Received: from mx-prod-mc-03.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-45-Kfx7Fj9xP72fnVeaz1iwQg-1; Tue, 27 Aug 2024 06:35:36 -0400 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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BCE731955D42; Tue, 27 Aug 2024 10:35:35 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.112]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 287021954B04; Tue, 27 Aug 2024 10:35:35 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C639A21E691E; Tue, 27 Aug 2024 12:35:32 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1724754939; 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=i4Q8o0IG0jTVd7vOErL8HdXdFcv0ZdMf445XvAP4iWo=; b=hbB2ipLbu+OuahLTUEcjiaIAbVsflFhjBKr+D0LaxUvT6u3phDtNKs/TtYmpTn4BJFgsi/ RVKuiHTCfr9g7b12tcPBMsdCDIuUiG/A1RUrZwtCmkxDXvobXaFGIcEEX6AKB5lpxjqdxV nh0ykMB6kkNA3p7ZjhrrfeBkVHH+sJ0= X-MC-Unique: Kfx7Fj9xP72fnVeaz1iwQg-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: richard.henderson@linaro.org, John Snow Subject: [PULL 1/1] docs/sphinx: fix extra stuff in TOC after freeform QMP sections Date: Tue, 27 Aug 2024 12:35:32 +0200 Message-ID: <20240827103532.799039-2-armbru@redhat.com> In-Reply-To: <20240827103532.799039-1-armbru@redhat.com> References: <20240827103532.799039-1-armbru@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=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_H3=0.001, RCVD_IN_MSPIKE_WL=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: 1724755000202116600 Content-Type: text/plain; charset="utf-8" From: John Snow Freeform sections with titles are currently generating a TOC entry for the first paragraph in the section after the header, which is not what we want. (Easiest to observe directly in the QMP reference manual's "Introduction" section.) When freeform sections are parsed, we create both a section header *and* an empty, title-less section. This causes some problems with sphinx's post-parse tree transforms, see also 2664f317 - this is a similar issue: Sphinx doesn't like section-less titles and it also doesn't like title-less sections. Modify qapidoc.py to parse text directly into the preceding section title as child nodes, eliminating the section duplication. This removes the extra text from the TOC. Only very, very lightly tested: "it looks right at a glance" :tm:. I am still in the process of rewriting qapidoc, so I didn't give it much deeper thought. Reported-by: Markus Armbruster Signed-off-by: John Snow Message-ID: <20240822204803.1649762-1-jsnow@redhat.com> --- docs/sphinx/qapidoc.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 738b2450fb..5f96b46270 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -388,6 +388,7 @@ def _start_new_heading(self, heading, level): self._active_headings[level - 1] +=3D snode self._active_headings =3D self._active_headings[:level] self._active_headings.append(snode) + return snode =20 def _add_node_to_current_heading(self, node): """Add the node to whatever the current active heading is""" @@ -417,13 +418,11 @@ def freeform(self, doc): # the first line of the block) (heading, _, text) =3D text.partition('\n') (leader, _, heading) =3D heading.partition(' ') - self._start_new_heading(heading, len(leader)) + node =3D self._start_new_heading(heading, len(leader)) if text =3D=3D '': return =20 - node =3D self._make_section(None) self._parse_text_into_node(text, node) - self._add_node_to_current_heading(node) self._cur_doc =3D None =20 def _parse_text_into_node(self, doctext, node): --=20 2.46.0