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 lists1p.gnu.org (lists1p.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 1A9ABCCFA13 for ; Wed, 29 Apr 2026 19:27:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZ1-0006wk-DV; Wed, 29 Apr 2026 15:27:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYl-0006gk-VH for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:00 -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 1wIAYj-0007sx-SL for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:59 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490816; 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=+IlVVKtNcBZg/WOApfTWZgKHPvH/4hX4GeKENZAPe3Y=; b=IunLrhFv9oOX3vsXsBPuHnJJaDEH0s1TADwoWj5ekJXoVw2owJtCox3CONJTT+EWrOl4bw K//3BQFS/mFBtTJIVENrK2TWSSkGeOoFqNFs7bcTeYdLGJLPp3QLfcUDEteZqT4tg5VveZ s25c+JIdc/KvVIhLqf3CuZEmu+08jFE= Received: from mx-prod-mc-01.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-332-Gq1PGyQtNECCdIVpC9I0zQ-1; Wed, 29 Apr 2026 15:26:51 -0400 X-MC-Unique: Gq1PGyQtNECCdIVpC9I0zQ-1 X-Mimecast-MFC-AGG-ID: Gq1PGyQtNECCdIVpC9I0zQ_1777490810 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 57F9E19560A5; Wed, 29 Apr 2026 19:26:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B037C1800446; Wed, 29 Apr 2026 19:26:46 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 08/13] qapi/docs: Add rendering for INTRO sections Date: Wed, 29 Apr 2026 15:26:06 -0400 Message-ID: <20260429192611.1581223-9-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 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: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 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: qemu development 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 The only real difference here is that we need to dedent all but the first line so that it renders correctly. We don't need to do this for members and features because they are always rendered as part of a field list directive which expects indented lines - Undecorated plaintext doesn't, so we chop the indent off. This does not reflow the text or mess with the source info in any way, so "blame" for error messages should be unchanged. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 70ab9cdc214..6b8e4ecd76a 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -35,6 +35,7 @@ from pathlib import Path import re import sys +import textwrap from typing import TYPE_CHECKING from docutils import nodes @@ -150,8 +151,14 @@ def add_lines( self, content: str, info: QAPISourceInfo, + dedent: bool = False, ) -> None: lines = content.splitlines(True) + + if dedent: + txt = "".join(lines[1:]) + lines[1:] = textwrap.dedent(txt).splitlines(True) + for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) @@ -223,13 +230,14 @@ def reformat_arobase(text: str) -> str: # Transmogrification helpers - def visit_paragraph(self, section: QAPIDoc.Section) -> None: + def visit_text(self, section: QAPIDoc.Section) -> None: # Squelch empty paragraphs. if not section.text: return + dedent = bool(section.kind == QAPIDoc.Kind.INTRO) self.ensure_blank_line() - self.add_lines(section.text, section.info) + self.add_lines(section.text, section.info, dedent) self.ensure_blank_line() def visit_member(self, section: QAPIDoc.ArgSection) -> None: @@ -367,7 +375,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None: section.text = self.reformat_arobase(section.text) if section.kind.name in ("PLAIN", "INTRO"): - self.visit_paragraph(section) + self.visit_text(section) elif section.kind == QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) if section.name == "q_dummy": -- 2.54.0