From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f45.google.com (mail-wr1-f45.google.com [209.85.221.45]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A24F430569F for ; Fri, 2 Oct 2026 23:01:20 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.45 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790982082; cv=none; b=EpvBS7IgUcEKcRCL/DOtmrvdt/EaUqWv263XuFng4kOe3KKnp/IZrblYnCabAFluLiPWUVS2NIVFWGGmaExlvr5WZjRu+SJXtxh7f1geuDWXKzO1MdrGPBZ6ew/7ai+p3tyBMimfei3sGXDxoAEvqJX8/xru9+0cEBkS4teP/Ok= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790982082; c=relaxed/simple; bh=Kkc+7wyLlEIrSW/ZGHpo+zCK4Drb6lnG4rA0ceiEaps=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=a3OqvY3DE/ZNC53KTkq9CT1FksECli/aT2jT9/XJhyQvuR6RS9QOGUWWJm3H93EPPODdca8gmGXtVKvfOc0aHJqJyEA+TkiBc1TDogVDJqdHr34GL5VCa8BAfEVOWiGdIQic4U5fCLdRgitXcmclRhlHStLIxQwAYUFlHcbUlLk= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=TNvn1srs; arc=none smtp.client-ip=209.85.221.45 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="TNvn1srs" Received: by mail-wr1-f45.google.com with SMTP id ffacd0b85a97d-48bbb06e746so3624f8f.3 for ; Fri, 02 Oct 2026 16:01:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1790982079; x=1791586879; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to:content-type; bh=BYvP6m3iDd7aVHdkDbM00AQcpjKk9yQSFhGJmwfSPZY=; b=TNvn1srs8a1H+p1N0oisFFcxm61XqQwdRWnNQnK54uY75a2bWWTqH7CULvhkXTubxi VSVO0pDTV/Gk6SMYZ8oRJofLXSBSwfBiDMT2H+QcI6623uXou5mVC6d7vPgccXr6hKgU TLL/cNKsFgd4+eW1tTLJkw1CaFuqh66epAVuN0YyUZS1imDBPYEx+MJtdTxvoytvBllM 2PQazgl+WQNNBz2Kn5g85gItj8w21FAvIWwRa7XWzmbUWjdDNRKrU+bOcLzKxYCxLDjG TKH4ZSHWn4tdIV1G7LljntHwG9XEr7xsAVJDgT4P3Df6s1oUywDpmLn9vs2w1J56ZCTp YK9Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20260707; t=1790982079; x=1791586879; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=BYvP6m3iDd7aVHdkDbM00AQcpjKk9yQSFhGJmwfSPZY=; b=RO0vRMurPZrXI7btB9KhPE7ZYVdVzZn3zq8NRVSFz+rxrVHtqOzrN0nYHfbxrBQFUQ 8snW+GKT3de/+CmUBdLyt4iHVLrf3ummYjLLoMNUes4GaKDfThrdYy9bTkXt/WJwZT32 ttZLf4I0CD2K39RPz134U/Zeun6mAG8gdWymDt4ZruOSexXi/V4sXzoylOCdPeOg3L5v whpRhCKwkVNoLSo7+ggto4fOoW5tUzep7w5ufZXPYNOlr4jRYQ8Yny1dapGSoWud+j0o u4OGuNiqR1cGmPDsLKSzNHDm8jUIw0YJ7lIZdWydqJrtWWXrCmvQp2JhS7UVeyjjpARj 70hw== X-Forwarded-Encrypted: i=1; AKwUvBy8y/a9sBrn5d93o5TAmkp+0/tGJ1d1B40r1ZWUMWp4fMP7KPAC/Ao/gBm7ilhP/MGQPbUtKie5x2E=@vger.kernel.org X-Gm-Message-State: AFq9FYIFz329TMvMo5xAd94zYxDwsbZfTn2Gx2tGgbqRP59atV8XYsi9 mFgVvQXzb/aQnwRMYXpnE365OENujbgOvtbkG/PioGrCFKPwfiQwX56c X-Gm-Gg: AYBFou3Zeusy20KehDx1AEzAsNRg/KsRPJjuRPlZ1VriM0bPBy4bB5Z0AxMEsshwl1b w5bKlwvG+N1ZjRzALaHck9nnFQ4MiEPc9sGT94EzQ8EGKBdjOtk8+Og/0/kt8VQpkX1NiHXwW6f 6usNcJfMg/dufXn6qJI3z7AzzpJABftf80R6WyAt6PdgJd4qyNvXWrfdTa/1LJOx/BJfYCqPm7F 7dD8KrL1ySJx19GaOSpiFPWHp/T9vSMwM+fGB50jUaaQlksx0xHfzKXVILqmE2LEDRkOzfvpLCE xd7GwGqJxWVqkOJHUyn01T+VdpsIi4qK/apD+QEaXA4RwmEsL+Y2ZeDBhpEv/sqcJK+13P+ot41 kQ9Gdmp67y2Dy8J+Kl0Y5HiPmC7I2A5zDTEnNMY/skT4+cRy7L08pMAkESOM1CsWOZdPX1JBfU6 5ntSXKrljnpFZlsAyBXtTUT8hqTefePe/5rV4ItgRfTgx9b1j7nXErzC+Iy9+HCe1xIwFs2Gkte EhKol66tlIiqdaPqAyMitZkthk56j3lAJ0AI7zmMPcpSmycrVehuMCcb6IYrPVvcvZ+f0Q3F4W8 /gVjfBpYUtbQrKke/0j+8zowOxKxRU5BS5LqxR0XzxPrk1YcgHs9hu+vMhQIFppk8L7B06VpZUT dSQ== X-Received: by 2002:a05:6000:25e3:b0:48a:f11a:c34a with SMTP id ffacd0b85a97d-48c4801ad09mr929694f8f.52.1790982078649; Fri, 02 Oct 2026 16:01:18 -0700 (PDT) Received: from localhost.localdomain (dynamic-2a02-3100-af35-1901-81da-eee8-c2d0-ee3b.310.pool.telefonica.de. [2a02:3100:af35:1901:81da:eee8:c2d0:ee3b]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-48b82253e8dsm7514734f8f.4.2026.10.02.16.01.17 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Fri, 02 Oct 2026 16:01:18 -0700 (PDT) From: Karl Mehltretter To: Jonathan Corbet Cc: Karl Mehltretter , Mauro Carvalho Chehab , Shuah Khan , Randy Dunlap , Jakub Kicinski , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH v3] docs: kerneldoc.py: preserve headings in kernel-doc output Date: Sat, 3 Oct 2026 01:01:14 +0200 Message-Id: <20261002230114.39651-1-kmehltretter@gmail.com> X-Mailer: git-send-email 2.39.5 (Apple Git-154) Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit kerneldoc.py parses extracted ReST into a detached section node while retaining the surrounding title hierarchy. Docutils 0.21.2 silently drops affected sections; 0.22.4 reports: Documentation/networking/kapi:107: ../include/net/net_shaper.h:75: ERROR: A level 3 section cannot be used here. The same issue drops three Xe DRM RAS headings already in mainline. Use nested_parse_with_titles() to give kernel-doc output an independent title hierarchy. Fixes: 2404dad1f67f ("doc: Cope with the deprecation of AutoReporter") Acked-by: Randy Dunlap Tested-by: Randy Dunlap Assisted-by: LLM Signed-off-by: Karl Mehltretter --- Reposted as a standalone documentation patch at Jakub's suggestion: https://lore.kernel.org/r/20260925120152.09ef180c@kernel.org/ Changes since v2: - Route the patch to the documentation maintainers without a net-next tag. - Add Randy's Acked-by and Tested-by tags. No code changes. Documentation/sphinx/kerneldoc.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index c1cadb4eb0997..9986df33e37ea 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -38,6 +38,7 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive import sphinx from sphinx.util.docutils import switch_source_input +from sphinx.util.nodes import nested_parse_with_titles from sphinx.util import logging from pprint import pformat @@ -252,7 +253,7 @@ class KernelDocDirective(Directive): def do_parse(self, result, node): with switch_source_input(self.state, result): - self.state.nested_parse(result, 0, node, match_titles=1) + nested_parse_with_titles(self.state, result, node) def setup_kfiles(app): global kfiles -- 2.53.0