Re: [PATCH net-next v2 2/2] docs: kerneldoc.py: preserve headings in kernel-doc output

[Randy Dunlap]

On 8/14/26 6:32 PM, Karl Mehltretter wrote:
> 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")
> Assisted-by: Codex:gpt-5.6-sol
> Signed-off-by: Karl Mehltretter <kmehltretter@xxxxxxxxx>

LGTM. Thanks.

Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

> ---
>  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

-- 
~Randy