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

[Karl Mehltretter]

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