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

[Randy Dunlap]

On 8/14/26 3:49 PM, Karl Mehltretter wrote:
> 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.

Please do so.
Thanks.

-- 
~Randy