From patchwork Wed Jun 26 22:21:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13713482 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 E3F52C27C4F for ; Wed, 26 Jun 2024 22:26:28 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sMb2T-0005W8-2A; Wed, 26 Jun 2024 18:22:53 -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 1sMb2P-0005US-4T for qemu-devel@nongnu.org; Wed, 26 Jun 2024 18:22:51 -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 1sMb2N-0002PZ-Jj for qemu-devel@nongnu.org; Wed, 26 Jun 2024 18:22:48 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1719440567; 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=kHogK1dBalwyaLyPoeKpitjOGb+mXJi51wzKjOYP2Ro=; b=L7ctapM8/1EK0u/kQvhMIrAisvkKAH0rklceNUeregBlH4uRo5zNVPlVw1fzZbUEam5rBG 5VYnxQl7RCV25/HH0i/035HWvbPmgGobatKa0LuUPsXb+fdIshndH7padiTfY2uGnjXKs4 0FM9FRX5XbWFsGfx8qzDy29yyiIEDxo= 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-524-vX3KeRADN0qZqIaEdG3fVA-1; Wed, 26 Jun 2024 18:22:42 -0400 X-MC-Unique: vX3KeRADN0qZqIaEdG3fVA-1 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 B818319560B5; Wed, 26 Jun 2024 22:22:39 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.8.67]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A4ED41955E72; Wed, 26 Jun 2024 22:22:32 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Mads Ynddal , Jiri Pirko , Stefan Hajnoczi , Eric Blake , Peter Maydell , Michael Roth , "Michael S. Tsirkin" , Alex Williamson , Pavel Dovgalyuk , Victor Toso de Carvalho , =?utf-8?q?C=C3=A9dric_Le_G?= =?utf-8?q?oater?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , qemu-block@nongnu.org, Ani Sinha , Fabiano Rosas , Marcel Apfelbaum , =?utf-8?q?Marc-Andr=C3=A9_Lu?= =?utf-8?q?reau?= , Gerd Hoffmann , Paolo Bonzini , Kevin Wolf , Peter Xu , Eduardo Habkost , Markus Armbruster , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Lukas Straub , Igor Mammedov , Jason Wang , Yanan Wang , Hanna Reitz , Konstantin Kostiuk , Stefan Berger , John Snow Subject: [PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged sections Date: Wed, 26 Jun 2024 18:21:13 -0400 Message-ID: <20240626222128.406106-8-jsnow@redhat.com> In-Reply-To: <20240626222128.406106-1-jsnow@redhat.com> References: <20240626222128.406106-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.207, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org 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 f9683444b14..efcd84656fa 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 == 'TODO': # Hide TODO: sections continue + + if not section.tag: + # Sphinx cannot handle sectionless titles; + # Instead, just append the results to the prior section. + container = nodes.container() + self._parse_text_into_node(section.text, container) + nodelist += container.children + continue + snode = self._make_section(section.tag) - if section.tag and section.tag.startswith('Example'): + if section.tag.startswith('Example'): snode += 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