From nobody Sun Nov 24 22:45:34 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=1720250739; cv=none; d=zohomail.com; s=zohoarc; b=Ko9f+378mquhtsgjbiIwasEW7h/0wPWq51OVbW1nuINxTJ+LycjfYdWa3Kz5MzrTzE+3jupapK4Rz95RGBv0BybKKdiNiiFJVZ53RbtmWwENdKVCxFE7pY0GzFb5mh7B+6xhMe7ouGvqcGDUPZEBeZ/GKUPcv6w92ZYscwJqSa0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1720250739; 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=OmqZMdFEKdP70Rpnbs/8ZQGf+j0M3yNoS27MM8SGGzk=; b=AlIlLxhDAc7JmJCmA3rFFC7Gz0jCRcQY7jQngOQDvUP3LPM6eX49SgganYor446U4yszg6jlOAsFGmc0+STa8O0vPMoC3OwNHWJZAG1U/uRN0eIGUJHX1FpHlqTI0OCG7JovLy9bQFCIhztjj+32Bp/KhLZQA87m78Y8tX7bjNg= 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 1720250739132925.6464933532388; Sat, 6 Jul 2024 00:25:39 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sPzmc-0006wX-Dr; Sat, 06 Jul 2024 03:24:35 -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 1sPzma-0006vd-QY for qemu-devel@nongnu.org; Sat, 06 Jul 2024 03:24:32 -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 1sPzmV-0004Z4-S8 for qemu-devel@nongnu.org; Sat, 06 Jul 2024 03:24:32 -0400 Received: from mx-prod-mc-05.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-313-hxRyei2bNxuOYf7Q0yMZ0A-1; Sat, 06 Jul 2024 03:24:22 -0400 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0C851195608B; Sat, 6 Jul 2024 07:24:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.4]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 66DB319560AA; Sat, 6 Jul 2024 07:24:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9739821F4B92; Sat, 6 Jul 2024 09:24:16 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720250664; 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=OmqZMdFEKdP70Rpnbs/8ZQGf+j0M3yNoS27MM8SGGzk=; b=IkI6YLQEP2sQTBpjQwZ7owkkWm9sYaNdt/1sBCOP1AFoIvGU+OhPsEZEelHhf2skpwdJGA IWKeqSmHIlEsyXo0T15y6zEsFJg9xuzB+H9G6zsD+yAd84lgX10n4OjTtYObbqpK42kicc smLkvDjbKmUYQ9CAqVNuhUwlJIRI4zU= X-MC-Unique: hxRyei2bNxuOYf7Q0yMZ0A-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: richard.henderson@linaro.org, John Snow Subject: [PULL 06/13] docs/qapidoc: fix nested parsing under untagged sections Date: Sat, 6 Jul 2024 09:24:09 +0200 Message-ID: <20240706072416.1717485-7-armbru@redhat.com> In-Reply-To: <20240706072416.1717485-1-armbru@redhat.com> References: <20240706072416.1717485-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 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_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: 1720250741276100003 Content-Type: text/plain; charset="utf-8" From: John Snow Sphinx does not like sections without titles, because it wants to convert every section into a reference. When there is no title, it struggles to do this and transforms the tree inproperly. Depending on the rST used, this may result in an assertion error deep in the docutils HTMLWriter. (Observed when using ".. admonition:: Notes" under such a section - When this is transformed with its own element, Sphinx is fooled into believing this title belongs to the section and incorrect mutates the docutils tree, leading to errors during rendering time.) When parsing an untagged section (free paragraphs), skip making a hollow section and instead append the parse results to the prior section. Many Bothans died to bring us this information. The resulting output changes are basically invisible. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-8-jsnow@redhat.com> [Mention output changes in commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com> --- docs/sphinx/qapidoc.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f9683444b1..efcd84656f 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -272,14 +272,20 @@ def _nodes_for_sections(self, doc): if section.tag and section.tag =3D=3D 'TODO': # Hide TODO: sections continue + + if not section.tag: + # Sphinx cannot handle sectionless titles; + # Instead, just append the results to the prior section. + container =3D nodes.container() + self._parse_text_into_node(section.text, container) + nodelist +=3D container.children + continue + snode =3D self._make_section(section.tag) - if section.tag and section.tag.startswith('Example'): + if section.tag.startswith('Example'): snode +=3D self._nodes_for_example(dedent(section.text)) else: - self._parse_text_into_node( - dedent(section.text) if section.tag else section.text, - snode, - ) + self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist =20 --=20 2.45.0