Skip to contentSkip to conversation

net_shaper: fix kernel-doc rendering

PATCH In review Karl Mehltretter 4 participants 9 messages Aug 15 – Sep 25

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

v2 cover net_shaper: fix kernel-doc rendering

The net_shaper_ops documentation contains a malformed ReST list and exposes a kerneldoc.py title-context bug which drops valid headings. Fix the list first because the parser correction makes it visible. The parser fix also restores three Xe DRM RAS headings already in mainline.

Tested with Sphinx 9.1.0:

Docutils 0.21.2 and 0.22.4:
make SPHINXDIRS=networking htmldocs

Docutils 0.22.4:
make htmldocs

The full output differed only in the intended net_shaper and Xe rendering and checkout-path-dependent build artifacts.

Changes from v1:
- fix heading parsing instead of replacing headings with bold labels
- split the list and parser fixes
- add diagnostics and point the Fixes tag at the kerneldoc.py regression

v1: https://lore.kernel.org/netdev/[email protected]/

Karl Mehltretter (2):
net_shaper: fix kernel-doc list indentation
docs: kerneldoc.py: preserve headings in kernel-doc output

 Documentation/sphinx/kerneldoc.py | 3 ++-
 include/net/net_shaper.h          | 9 +++++----
 2 files changed, 7 insertions(+), 5 deletions(-)

base-commit: 3205699d79f262412c1be7fc1c04066610d3cd52

Signature · 1 line
2.53.0
#1 lore raw

PATCH v2 1/2 net_shaper: fix kernel-doc list indentation

Docutils 0.22.4 reports:

Documentation/networking/kapi:107:
../include/net/net_shaper.h:82:
ERROR: Unexpected indentation.

Add the required blank line and correct the list indentation.

Assisted-by Codex:gpt-5.6-sol
---
 include/net/net_shaper.h | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
include/net/net_shaper.h +5 -4
index 05cb625b0fe54..330517a1cb5c2 100644
@@ -80,10 +80,11 @@ struct net_shaper {
  * disallowed at the uAPI level will never be made at the driver level.
  * The shaper core performs automatic reparenting and cleanup, generating
  * additional calls. Notably:
- *  - @group calls in the driver facing API may have nodes as leaves (user is
- *    only allowed to construct groups with queues as leaves)
- *  - @group calls may update leaf's parent if the parent is about
- *    to be removed (re-parenting nodes explicitly is not supported in the uAPI)
+ *
+ * - @group calls in the driver facing API may have nodes as leaves (user is
+ *   only allowed to construct groups with queues as leaves)
+ * - @group calls may update leaf's parent if the parent is about
+ *   to be removed (re-parenting nodes explicitly is not supported in the uAPI)
  *
  * Implicit creation
  * -----------------
Signature · 1 line
2.53.0
reviewer Reviewed-by Tested-by on v2 1/2
#2 lore raw

Re: [PATCH net-next v2 1/2] net_shaper: fix kernel-doc list indentation

Quoted 10 lines · Karl Mehltretter

Docutils 0.22.4 reports:

Documentation/networking/kapi:107:
../include/net/net_shaper.h:82:
ERROR: Unexpected indentation.

Add the required blank line and correct the list indentation.

Assisted-by Codex:gpt-5.6-sol

Thanks.

Quoted 24 lines
---
 include/net/net_shaper.h | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)
include/net/net_shaper.h +5 -4
index 05cb625b0fe54..330517a1cb5c2 100644
@@ -80,10 +80,11 @@ struct net_shaper {
  * disallowed at the uAPI level will never be made at the driver level.
  * The shaper core performs automatic reparenting and cleanup, generating
  * additional calls. Notably:
- *  - @group calls in the driver facing API may have nodes as leaves (user is
- *    only allowed to construct groups with queues as leaves)
- *  - @group calls may update leaf's parent if the parent is about
- *    to be removed (re-parenting nodes explicitly is not supported in the uAPI)
+ *
+ * - @group calls in the driver facing API may have nodes as leaves (user is
+ *   only allowed to construct groups with queues as leaves)
+ * - @group calls may update leaf's parent if the parent is about
+ *   to be removed (re-parenting nodes explicitly is not supported in the uAPI)
  *
  * Implicit creation
  * -----------------
Signature · 1 line
~Randy
#3 lore raw

PATCH v2 2/2 docs: kerneldoc.py: preserve headings in kernel-doc output

In reply to Karl Mehltretter

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
---
 Documentation/sphinx/kerneldoc.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/kerneldoc.py +2 -1
index c1cadb4eb0997..9986df33e37ea 100644
@@ -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
Signature · 1 line
2.53.0
reviewer Acked-by Tested-by on v2 2/2
#4 lore raw

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

Quoted 8 lines · Karl Mehltretter

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.

Quoted 8 lines

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

LGTM. Thanks.

Quoted 25 lines
---
 Documentation/sphinx/kerneldoc.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/kerneldoc.py +2 -1
index c1cadb4eb0997..9986df33e37ea 100644
@@ -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
Signature · 1 line
~Randy
#5 lore raw

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

In reply to Karl Mehltretter
Quoted 2 lines · On Sat, 15 Aug 2026 03:32:29 +0200, I wrote:

Use nested_parse_with_titles() to give kernel-doc output an independent title hierarchy.

Friendly ping on v2. It already has Acked-by and Tested-by tags.

Is anything else needed from my side before this can be picked up?

Thanks,
Karl

#6 lore raw
In reply to Karl Mehltretter
This series was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:

Hello:

This series was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:

Quoted 8 lines · On Sat, 15 Aug 2026 03:32:27 +0200 you wrote:

The net_shaper_ops documentation contains a malformed ReST list and exposes a kerneldoc.py title-context bug which drops valid headings. Fix the list first because the parser correction makes it visible. The parser fix also restores three Xe DRM RAS headings already in mainline.

Tested with Sphinx 9.1.0:

[...]

Here is the summary with links:
- [net-next,v2,1/2] net_shaper: fix kernel-doc list indentation

    https://git.kernel.org/netdev/net-next/c/09b7c00d55a8

- [net-next,v2,2/2] docs: kerneldoc.py: preserve headings in kernel-doc output (no matching commit)

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
reviewer
#7 lore raw

Karl M. wrote:
| Friendly ping on v2. It already has Acked-by and Tested-by tags.

| Is anything else needed from my side before this can be picked up?

Quoted 15 lines · On 8/17/26 2:00 PM, [email protected] wrote:

Hello:

This series was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:

Quoted 8 lines · On Sat, 15 Aug 2026 03:32:27 +0200 you wrote:

The net_shaper_ops documentation contains a malformed ReST list and exposes a kerneldoc.py title-context bug which drops valid headings. Fix the list first because the parser correction makes it visible. The parser fix also restores three Xe DRM RAS headings already in mainline.

Tested with Sphinx 9.1.0:

[...]

Quoted 7 lines

Here is the summary with links:
- [net-next,v2,1/2] net_shaper: fix kernel-doc list indentation

    https://git.kernel.org/netdev/net-next/c/09b7c00d55a8

- [net-next,v2,2/2] docs: kerneldoc.py: preserve headings in kernel-doc output (no matching commit)

You are awesome, thank you!

so these 2 patches are merged into net-next, which should be merged into mainline Linux at the next merge window (in the 2 weeks after Linux v7.3 is released).

Patch 1/2 is in the current linux-next daily releases. However, patch 2/2 is not merged anywhere in linux-next AFAICT.

I also would like to see patch 2/2 merged...

Signature · 1 line
~Randy
maintainer
#8 lore raw
Quoted 8 lines · On Thu, 24 Sep 2026 16:13:05 -0700 Randy Dunlap wrote:
Quoted 7 lines

Here is the summary with links:
- [net-next,v2,1/2] net_shaper: fix kernel-doc list indentation

    https://git.kernel.org/netdev/net-next/c/09b7c00d55a8

- [net-next,v2,2/2] docs: kerneldoc.py: preserve headings in kernel-doc output (no matching commit)

You are awesome, thank you!

Quoted 8 lines

so these 2 patches are merged into net-next, which should be merged into mainline Linux at the next merge window (in the 2 weeks after Linux v7.3 is released).

Patch 1/2 is in the current linux-next daily releases. However, patch 2/2 is not merged anywhere in linux-next AFAICT.

I also would like to see patch 2/2 merged...

Sorry, maybe I should have called it out more explicitly instead of expecting people to read the pw-bot reply. Yes, I only took the networking change. I think it's easiest if Karl reposts the other one for Jon to apply? (without tagging it for net-next of course)