Re: [PATCH v3] docs: kerneldoc.py: preserve headings in kernel-doc output

[Jonathan Corbet <corbet@lwn.net>]

Karl Mehltretter <kmehltretter@gmail.com> writes:

> 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")
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
> Reposted as a standalone documentation patch at Jakub's suggestion:
> https://lore.kernel.org/r/20260925120152.09ef180c@kernel.org/
>
> Changes since v2:
> - Route the patch to the documentation maintainers without a net-next tag.
> - Add Randy's Acked-by and Tested-by tags. No code changes.

Which versions of Sphinx and docutils have you tested this with?  I
needs to work across the full range of supported versions...

Thanks,

jon