From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f43.google.com (mail-wr1-f43.google.com [209.85.221.43]) (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 A70A93A8FF6 for ; Fri, 14 Aug 2026 22:49:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.43 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786747788; cv=none; b=Q3wfMs7Xs1NSXb8pkKl9HCuplEPG/x4wqSqvc9ZxmWy9q0mD56eI4G5PE9YO5FAaM91PtMTEN3xKR7sQkFNEgnhTzl0NJCf5A04QY3sfXzJHTcs974RQ9TxpfJP8NL8wxMjeXO3ZiYLoQbHY2Qh6ij5841DCeHOghY90EiWdqdg= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786747788; c=relaxed/simple; bh=Uj2+R/XlIIBkzBOTJl+GOwS1l87hHD9TviV6bZAx7kY=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=BpsqfVhGP0SmfQWCYRa0F/06WOIcfPKrREhFBmBRicQOv+VP/bAUPgFfcQ38OBZpLWhE7nw8t3nsBB4W2uYKtgGxuNjkiZg6gxIqIxRfB8X0u4FYOw+MAGpJhaGvNPD8q2an6sn1Cp6mW+KrR9/bwwR/TiHp34+d9XY4GARbo3Q= 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=I3rN+lFC; arc=none smtp.client-ip=209.85.221.43 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="I3rN+lFC" Received: by mail-wr1-f43.google.com with SMTP id ffacd0b85a97d-47f633e6058so1336588f8f.0 for ; Fri, 14 Aug 2026 15:49:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1786747785; x=1787352585; darn=vger.kernel.org; h=in-reply-to:content-disposition:content-type:mime-version :references:message-id:subject:cc:to:from:date:from:to:cc:subject :date:message-id:reply-to:content-type; bh=AXr1BCwnVUg1iSuJ2/QuEA4a6oezRbOQNZkSmQqG+MI=; b=I3rN+lFCImZcC0GU2DKz0KIxeDllzGi6w9FPm6LQibHQWZrpATi0WW9XF2P8CuK5S7 KHhidyGIve1nCDBtEbYkuXCCD8A9bHKvvBqCMmcLJhdVfEA+YRDF7YNg2vCpn0cTuF+U hWIxaFLD9dAglEKkLVZzcxtCaSzNHVtI21uRFPSzi+pJgpBdUQnHzyvTnjrwDzVGUzvT 1EOkU+bSyMqshXFBPih4n1pxfWmM0s8HNFUxI6malr9ybS4c4gDnMQkcCsXKXDsihvYP pTvvXP+WTuyuBh4MdL2xceDhTi7F5+2mvHr1XhOZP/gSVWq7ypcu+ZjKbTr/hS11MOD/ jhIw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1786747785; x=1787352585; h=in-reply-to:content-disposition:content-type:mime-version :references:message-id:subject:cc:to:from:date:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=AXr1BCwnVUg1iSuJ2/QuEA4a6oezRbOQNZkSmQqG+MI=; b=W6GAfc4pJqYw5Ig8j1qnjfyDclsrORIs8y9B3oF39F2X1vT40H4BZ4jIZthwRzHqxb zqSU7BxYbOo9a7Q+C62LZPRtoMQst8YhyRLl6zK67WbF71VUk2WRCt5KYYI/myNSO5Xp qITOVmKaFPaWDfbICpB9aZjkoQgMhJaYgJlJ/6WDHLup2XBABNHVoEtfdsyOnZA2Bnqy BZlAXVOLDKSBH1Qr3ZJxO9j7t6aiFWergrB/XHudj0u9jF88E6ggxnUv6xvzjnD4bzHT mxAxWWatdU2U0pA+9Lde6SkCaV61NCLGLWxZ/ASBFeCVHdPPXZ8DLb9Ypvu5lOB0/SGM 36uA== X-Forwarded-Encrypted: i=1; AHgh+RqORkS2WVgIpq2uNGSPC83cfp9TbMZAWr2/pyZvUbfkt0H5y/J9zzqRO9RnAs/AVs/JW55mQNOH6JbBV04=@vger.kernel.org X-Gm-Message-State: AOJu0Yxj3ElyzQsSDz4+6lOb2Zyv+ujMHLREcL6CjPQ6QqS+mmumnDGk G5yGUIb7DUSBdcW0NwesiwNp4dQiilnKFBVi2dd5eCoBcync1QGmvLdR X-Gm-Gg: AR+sD11W3fBDAzk2D4Wj5N9Hg97wcbZjTNsn9CS+5WI1JPpm21QJo5L6r+1OdKoGdAb CWw5sCzv+GBRQ0FV21vJGmbzY99rRufbvmSIR59CD/KVr3bazXyeJl80p94qQCzDs5g7ErKIyop gYQ1zkcna4e3oROYXm5SmvofOY8odDfwAZ92LvAlf3M9Fh5PNeQjOf4OsM93hSw8I65/tSqTUNl ueWL87yDZIuS9Y/1AF5m01Sm/7OhxJgcAiS9he2hvACHDUqpNO7tTWl7y9aA0amKhPemjExdqt3 8E0WOzHiFjxAPPGAAMV55RwuYJXgYKUIEVd11tE/FqrPZAuJeA3sWY2cKUyDTtbPfOn2lDfE3Lx UFFVtooSiHapLZPgu80pcEy434MwyTAgbqqVlbXNVsltR/FW5OkVWlgl8sPiQ8QJUqqIQFV3qv4 SAf3f2xNcRDDSNyJSSwki/2JXcF5x68kWd8/WKiy28wk3fbEK/Pltfl3gIf76sLeaRArJTCg3no mEgWMBGnFxTlXfXtBGKRhWSvBmBXJtuDIlpTb2YuXqAyblciY6uQPZ/xg6rIP9nNGdp/xJTZX/9 e5FKFSgdFtk1cd0UewZyz0XTJ078vVsXNgpgNQ9KsVY+hkNNgZwjAxb8rqMlX3ZGTw== X-Received: by 2002:a05:6000:29da:b0:47f:4fa9:ae42 with SMTP id ffacd0b85a97d-48160759b98mr8911102f8f.11.1786747784612; Fri, 14 Aug 2026 15:49:44 -0700 (PDT) Received: from unknown748F3CBA5068 (dynamic-2a02-3100-9d7d-f301-9495-44ec-73e6-1be7.310.pool.telefonica.de. [2a02:3100:9d7d:f301:9495:44ec:73e6:1be7]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-48294e70f8asm3029024f8f.11.2026.08.14.15.49.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 14 Aug 2026 15:49:44 -0700 (PDT) Date: Sat, 15 Aug 2026 00:49:41 +0200 From: Karl Mehltretter To: Randy Dunlap Cc: Jakub Kicinski , "David S. Miller" , Eric Dumazet , Paolo Abeni , Simon Horman , netdev@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, Jonathan Corbet Subject: Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc Message-ID: References: <20260813192131.21254-1-kmehltretter@gmail.com> <20260814101408.13bc8cc2@kernel.org> <984e036c-0d90-435f-a56b-ea39a2adf923@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <984e036c-0d90-435f-a56b-ea39a2adf923@infradead.org> On Fri, Aug 14, 2026 at 12:04:05PM +0100, Randy Dunlap wrote: > On 8/14/26 10:14 AM, Jakub Kicinski wrote: > > > > Isn't this a problem in kernel-doc extraction / how we embed it for > > rendering? Heading are quite useful and IMHO far more natural to use. > > My understanding was that kdoc should be able to use basic ReST > > formatting. > > > > Ack on the list indent fix > > > > I don't know of another reasonable solution for this (although I'm no expert > on ReST), so > Yes, this is a problem in how Documentation/sphinx/kerneldoc.py embeds kernel-doc output. It parses generated content into a detached node while retaining the surrounding title hierarchy. The key kerneldoc.py change is replacing the parser call: - self.state.nested_parse(result, 0, node, match_titles=1) + nested_parse_with_titles(self.state, result, node) This preserves the headings. I tested the networking documentation with Sphinx 9.1.0 and Docutils 0.21.2 and 0.22.4, and a full htmldocs build with Docutils 0.22.4. The full build produced only unrelated existing warnings. I can send this as a two-patch v2, with the list correction first. Thanks, Karl