mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Randy Dunlap <rdunlap@infradead.org>
To: Karl Mehltretter <kmehltretter@gmail.com>,
	"David S. Miller" <davem@davemloft.net>,
	Eric Dumazet <edumazet@google.com>,
	Jakub Kicinski <kuba@kernel.org>, Paolo Abeni <pabeni@redhat.com>,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	Jonathan Corbet <corbet@lwn.net>
Cc: Shuah Khan <skhan@linuxfoundation.org>,
	Simon Horman <horms@kernel.org>,
	netdev@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH net-next v2 2/2] docs: kerneldoc.py: preserve headings in kernel-doc output
Date: Sun, 16 Aug 2026 10:14:32 -0700	[thread overview]
Message-ID: <6b59ab1c-9d3a-4f2a-823a-2cf61c5ea608@infradead.org> (raw)
In-Reply-To: <335fec1cd5a3449687f8b1ee8cd46a0f3e455aa5.1786751700.git.kmehltretter@gmail.com>



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

  reply	other threads:[~2026-08-16 17:14 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-08-15  1:32 [PATCH net-next v2 0/2] net_shaper: fix kernel-doc rendering Karl Mehltretter
2026-08-15  1:32 ` [PATCH net-next v2 1/2] net_shaper: fix kernel-doc list indentation Karl Mehltretter
2026-08-16 17:13   ` Randy Dunlap
2026-08-15  1:32 ` [PATCH net-next v2 2/2] docs: kerneldoc.py: preserve headings in kernel-doc output Karl Mehltretter
2026-08-16 17:14   ` Randy Dunlap [this message]
2026-09-19  5:30   ` Karl Mehltretter
2026-08-17 21:00 ` [PATCH net-next v2 0/2] net_shaper: fix kernel-doc rendering patchwork-bot+netdevbpf
2026-09-24 23:13   ` Randy Dunlap
2026-09-25 19:01     ` Jakub Kicinski

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=6b59ab1c-9d3a-4f2a-823a-2cf61c5ea608@infradead.org \
    --to=rdunlap@infradead.org \
    --cc=corbet@lwn.net \
    --cc=davem@davemloft.net \
    --cc=edumazet@google.com \
    --cc=horms@kernel.org \
    --cc=kmehltretter@gmail.com \
    --cc=kuba@kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab@kernel.org \
    --cc=netdev@vger.kernel.org \
    --cc=pabeni@redhat.com \
    --cc=skhan@linuxfoundation.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®