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

[Mauro Carvalho Chehab]

On Wed, 14 Oct 2026 11:08:39 -0600
Jonathan Corbet <corbet@xxxxxxx> wrote:

> Karl Mehltretter <kmehltretter@xxxxxxxxx> 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 backward-compatible fix is to ensure that the title markups will
be used on a consistent way, e.g., if:

- level 1 uses "====\n" + title + "\n===="
- level 2 uses "===="
- level 3 uses "----"
- level 4 uses "^^^^"

at the main doc, the kernel-doc tags shall follow the same schema,
e.g. if they are included at level 3, it has to use the level 4
markup.

So, in the specific case of kapi.rst, you can't use "====" nor
"----" inside net_shaper.h, as those are level 2 and level 3.
so, it has to use, for instance, "^^^^".

Yet, it is hard to make this on a consistent way and keep it
maintainable. The best is not use titles inside kernel-doc.

> >
> > 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@xxxxxxxxxxxxx>
> > Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> > Assisted-by: LLM
> > Signed-off-by: Karl Mehltretter <kmehltretter@xxxxxxxxx>
> > ---
> > Reposted as a standalone documentation patch at Jakub's suggestion:
> > https://lore.kernel.org/r/20260925120152.09ef180c@xxxxxxxxxx/
> >
> > 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...

The minimal docutils supported is 0.16, and the minimal Sphinx
supported version is 3.4.4.

You can use /tools/docs/test_doc_build.py to double check if your change
is compatible with the minimal supported Sphinx/docutils versions.

Just run the script:

	$ tools/docs/test_doc_build.py -b

and wait (*) for it to download supported versions and test if this breaks 
something. Notice that "-b" picks only the most significant versions:

  DEFAULT_VERSIONS_TO_TEST = [
    (3, 4, 3),   # Minimal supported version
    (5, 3, 0),   # CentOS Stream 9 / AlmaLinux 9
    (6, 1, 1),   # Debian 12
    (7, 2, 1),   # openSUSE Leap 15.6
    (7, 2, 6),   # Ubuntu 24.04 LTS
    (7, 4, 7),   # Ubuntu 24.10
    (7, 3, 0),   # openSUSE Tumbleweed
    (8, 1, 3),   # Fedora 42
    (8, 2, 3)    # Latest version - covers rolling distros
  ]

e.g. the ones found on distros up to Fedora 42 and the latest version
on that time.

to be really sure, use "-f" to test all possible versions.

(*) even with the simplified version checks, ti runs for quite a while: 
some versions take ~20 mins to build docs.

-

Jon,

I'll likely submit a patch soon to add 9.0 and 9.1 to the above list,
after finish running the tests here to see if the scripts need other
updates.

Thanks,
Mauro