[PATCH net-next v2 0/2] net_shaper: fix kernel-doc rendering

[PATCH net-next v2 0/2] net_shaper: fix kernel-doc rendering

[Karl Mehltretter]

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/20260813192131.21254-1-kmehltretter@gmail.com/

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
-- 
2.53.0

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

[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
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 include/net/net_shaper.h | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
index 05cb625b0fe54..330517a1cb5c2 100644
--- a/include/net/net_shaper.h
+++ b/include/net/net_shaper.h
@@ -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
  * -----------------
-- 
2.53.0

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

[Randy Dunlap]

On 8/14/26 6:32 PM, Karl Mehltretter wrote:
> 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
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  include/net/net_shaper.h | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
> index 05cb625b0fe54..330517a1cb5c2 100644
> --- a/include/net/net_shaper.h
> +++ b/include/net/net_shaper.h
> @@ -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
>   * -----------------

-- 
~Randy

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

[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
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 Documentation/sphinx/kerneldoc.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index c1cadb4eb0997..9986df33e37ea 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -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
-- 
2.53.0

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

[Randy Dunlap]

On 8/14/26 6:32 PM, Karl Mehltretter wrote:
> 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
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>

LGTM. Thanks.

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/sphinx/kerneldoc.py | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index c1cadb4eb0997..9986df33e37ea 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -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

-- 
~Randy

Re: [PATCH net-next v2 0/2] net_shaper: fix kernel-doc rendering

[patchwork-bot+netdevbpf]

Hello:

This series was applied to netdev/net-next.git (main)
by Jakub Kicinski <kuba@kernel.org>:

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!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html