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

[Karl Mehltretter]

On Wed, Oct 14, 2026 at 11:46:13PM +0100, Mauro Carvalho Chehab wrote:
> On Wed, 14 Oct 2026 11:08:39 -0600
> Jonathan Corbet <corbet@xxxxxxx> wrote:
> 
> > 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.
> 

I completed the A/B matrix using tools/docs/test_doc_build.py -f. The
full matrix shows the improvement without a regression. 

I also tested Sphinx 9.0.0, 9.0.4, and 9.1.0, plus the previously
discussed Sphinx 9.1.0 / Docutils 0.21.2 pair.

In total, this covered 32 combinations and 64 full htmldocs builds: A
unpatched and B patched.

Successful, with identical A/B output and normalized diagnostics (26):

  Docutils  Sphinx
  --------  --------------------------------------------------------
  0.16      3.4.3, 3.5.0, 4.0.0
  0.17      4.1.0, 4.3.0, 4.4.0
  0.17.1    4.5.0, 5.0.0, 5.1.0
  0.18      5.2.0
  0.18.1    5.3.0, 6.0.0, 6.1.0, 6.1.1, 6.2.0, 7.0.0, 7.1.0
  0.20      7.2.6, 7.3.0
  0.20.1    7.4.0, 7.4.7
  0.21      8.0.0
  0.21.1    8.1.0, 8.1.3
  0.21.2    8.2.0, 9.1.0

Successful, with only the intended A/B output change (2):

  Sphinx  Docutils  Normalized diagnostics  Changed output
  ------  --------  ----------------------  --------------------------
  8.2.3   0.21.2    62 -> 62, identical     networking/kapi.html,
                                             searchindex.js
  9.1.0   0.22.4    74 -> 60, removals only networking/kapi.html,
                                             searchindex.js

Identical pre-existing failure before and after the patch (4):

  Sphinx         Docutils  Status A/B  Normalized diagnostics A/B
  -------------  --------  ----------  --------------------------
  7.2.0, 7.2.1   0.19      2 / 2       191 / 191, identical
  9.0.0, 9.0.4   0.22      2 / 2        53 /  53, identical

No combination gained a diagnostic or changed its build result. The
only generated-output differences were the intended restored headings
and derived anchors. 

Karl