From nobody Mon Nov 25 04:42:23 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=1718757155; cv=none; d=zohomail.com; s=zohoarc; b=U84Lk6P0IICy7watbHK5hA+KBiR2xEIBb+JjzOOUsBFs86vYCMKrR5Uen/kOaxVqg16ANtrcSjJpVQVu4znxVLEf/9G4DQsglDxJOATo+YwiUGK3COvvXbTpo8EC8ApmFPFO4NoQjnIJk0gdWGYhsYpS1ODa3aE1HiFxRimntaE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1718757155; 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=PKn8SIxGob2pKMM70MaK6Zu4lcrmGDuuPfEZ9b3S+uQ=; b=WMBj9xiw53QVRiPIe4vK+jVTMUa+A8v9LQtS6VFCaLyVWXbxOVV0EjefoBgcbPQepdVGGumD9SDIHWHxcaVWch036p9VAM4zk0F6CyUFpS+rnjn8Wqq3KFQN0qe/cf20fkZN/KN8mEknyaa3iKzWcN3Ii/TNYbLRYY6xSiZ+y80= 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 1718757155153935.0280632548562; Tue, 18 Jun 2024 17:32:35 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sJjEX-0006eD-TA; Tue, 18 Jun 2024 20:31:29 -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 1sJjEW-0006as-8f for qemu-devel@nongnu.org; Tue, 18 Jun 2024 20:31:28 -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 1sJjEU-0001Qi-RV for qemu-devel@nongnu.org; Tue, 18 Jun 2024 20:31:28 -0400 Received: from mx-prod-mc-02.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-402-4OkzGxRBOvGFq_PlNjrGvQ-1; Tue, 18 Jun 2024 20:31:23 -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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6E40319560B2; Wed, 19 Jun 2024 00:31:20 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.16.38]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id F122A1955E80; Wed, 19 Jun 2024 00:31:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718757086; 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=PKn8SIxGob2pKMM70MaK6Zu4lcrmGDuuPfEZ9b3S+uQ=; b=SpJWRUGht3tE81yX0TJpPKN0zmw8AySpTbAzHFY/zEHpoCvRREdtO2GxVlMz6yFMYZ/ujf wlhnEzYfsivsNoYLb2KjlfFhW5GzRf6D14wGqexJjHqCaAdMGLxN9cpAZXd1wu6FMSTMRs RTikvAPY8EgPtVqDbLrpaRxqLH6eX3s= X-MC-Unique: 4OkzGxRBOvGFq_PlNjrGvQ-1 From: John Snow To: qemu-devel@nongnu.org Cc: Stefan Hajnoczi , Hanna Reitz , Michael Roth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Victor Toso de Carvalho , "Michael S. Tsirkin" , Konstantin Kostiuk , Yanan Wang , Pavel Dovgalyuk , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Marcel Apfelbaum , Fabiano Rosas , Lukas Straub , Eduardo Habkost , Mads Ynddal , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Gerd Hoffmann , Stefan Berger , Peter Xu , Igor Mammedov , =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , Jason Wang , Ani Sinha , Markus Armbruster , Paolo Bonzini , Peter Maydell , qemu-block@nongnu.org, Jiri Pirko , Alex Williamson , Kevin Wolf , Eric Blake , John Snow Subject: [PATCH 06/13] docs/qapidoc: fix nested parsing under untagged sections Date: Tue, 18 Jun 2024 20:30:05 -0400 Message-ID: <20240619003012.1753577-7-jsnow@redhat.com> In-Reply-To: <20240619003012.1753577-1-jsnow@redhat.com> References: <20240619003012.1753577-1-jsnow@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.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 11 X-Spam_score: 1.1 X-Spam_bar: + X-Spam_report: (1.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.148, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no 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: 1718757157060100015 Content-Type: text/plain; charset="utf-8" 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. Signed-off-by: John Snow <jsnow@redhat.com> Acked-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 f2f2005dd5f..66cf254a624 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -286,14 +286,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.44.0