net_shaper: fix kernel-doc rendering
Subsystems (4)
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
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.
--- include/net/net_shaper.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-)
include/net/net_shaper.h +5 -4
@@ -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
PATCH v2 2/2 docs: kerneldoc.py: preserve headings in kernel-doc output
In reply to Karl Mehltretterkerneldoc.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.
--- Documentation/sphinx/kerneldoc.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/kerneldoc.py +2 -1
@@ -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
Re: [PATCH net-next v2 1/2] net_shaper: fix kernel-doc list indentation
In reply to Karl MehltretterQuoted 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-solSigned-off-by Karl Mehltretter <[email protected]>
Thanks.
Quoted 24 lines
--- include/net/net_shaper.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-)include/net/net_shaper.h +5
-4@@ -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
Re: [PATCH net-next v2 2/2] docs: kerneldoc.py: preserve headings in kernel-doc output
In reply to Karl MehltretterQuoted 8 lines · Karl Mehltretter
kerneldoc.pyparses 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-solSigned-off-by Karl Mehltretter <[email protected]>
LGTM. Thanks.
Quoted 25 lines
--- Documentation/sphinx/kerneldoc.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/sphinx/kerneldoc.py +2
-1@@ -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
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_opsdocumentation contains a malformed ReST list and exposes akerneldoc.pytitle-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
Re: [PATCH net-next v2 2/2] docs: kerneldoc.py: preserve headings in kernel-doc output
In reply to Karl MehltretterQuoted 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
Randy Dunlap
reviewerKarl 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_opsdocumentation contains a malformed ReST list and exposes akerneldoc.pytitle-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 indentationhttps://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
Jakub Kicinski
maintainerQuoted 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 indentationhttps://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)