Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

On 8/14/26 3:49 PM, Karl Mehltretter wrote:

On Fri, Aug 14, 2026 at 12:04:05PM +0100, Randy Dunlap wrote:

quoted

On 8/14/26 10:14 AM, Jakub Kicinski wrote:

quoted

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.

Please do so.
Thanks.

-- 
~Randy