From nobody Mon Nov 25 11:21:04 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=1715724223; cv=none; d=zohomail.com; s=zohoarc; b=Oa3f6krARetyEqKlHLr2mCJntQiBt7QAjEyPd6LsWO0v/F8MH/S35ByU/i4/LSTS0QkF4HEVlX9tDOVEZkbTTVGO+22lid3oRXkA/iP1pwoapW4AXnw9HfjAPzUMirVTpGXxmqxghA9woHjvWFwLbXtCNEO3OEkrbSWAvY6iI/M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724223; 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=+2kDCXDoldCk9Iu0s+DkhAlixvACFVCHN/kg8zLipPY=; b=oIP34RZm7lnQNUO3AuwhXm/Gurw93kReaXB1749PG1yGT46EbgdFsYE4Hxx96cEXI6MVNr6461RRKw0iAzg9D9jyGkV/O4bsqG/DgLLDHOq8MSknYXev6/uatIHTNLpcg4P0SBpRprqiKUop1UNP9iyJXxH6+cRqAWzpSnZJeEM= 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 17157242230058.737465307798743; Tue, 14 May 2024 15:03:43 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AR-0005lP-El; Tue, 14 May 2024 17:58:39 -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 1s70AN-0005iH-UP for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -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 1s70AJ-00006l-Co for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-591-OyDoAmiNP52l-g4uPCLcbQ-1; Tue, 14 May 2024 17:58:27 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B24703806704; Tue, 14 May 2024 21:58:26 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7AC176BC5; Tue, 14 May 2024 21:58:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723910; 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=+2kDCXDoldCk9Iu0s+DkhAlixvACFVCHN/kg8zLipPY=; b=MjNTGumbjZbQ6mj3x0xq/IaWLx1uR6Rz+GNid8Gw5jPsRFk7vmM/h4uvfF0gKYyvGeGsNu psRB7tOg3/PbL/WvwNtVPDU6gT8fFPTodDaTR6evSY0JZFask0mXQymjEcSFDPnIfZ8S8U r7shnsXw4oeIYOHr5df7E71+N4gu3tI= X-MC-Unique: OyDoAmiNP52l-g4uPCLcbQ-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 13/20] docs/qapidoc: fix nested parsing under untagged sections Date: Tue, 14 May 2024 17:57:32 -0400 Message-ID: <20240514215740.940155-14-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, 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: 1715724223492100001 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. 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 --- 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 34e95bd168d..cfc0cf169ef 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