Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Jakub Kicinski]

Adding the missing CC of linux-doc

On Thu, 13 Aug 2026 21:21:31 +0200 Karl Mehltretter wrote:
> Everything from the "Driver ops vs uAPI" heading onward is dropped from
> the rendered net_shaper_ops documentation. Older Docutils versions do so
> silently, while Docutils 0.22 reports the nested headings and adjacent
> list as invalid.

Isn't this a problem in kernel-doc extraction / how we embed it for
rendering? Heading are quite useful and IMHO far more natural to use.
My understanding was that kdoc should be able to use basic ReST
formatting.

Ack on the list indent fix

> Use bold labels and correct the list indentation.
> 
> Fixes: 16812d9674d4 ("net_shaper: remove incorrect comment about group leaves")
> Fixes: 26bc4cfb1737 ("net_shaper: clarify the kernel API / comments")

This is a doc patch, please don't sprinkle Fixes tag on patches which
don't fix bugs.

> Assisted-by: Codex:gpt-5.6-sol
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
> The omission is visible in the current linux-next generated documentation:
> https://www.kernel.org/doc/html/next/networking/kapi.html#c.net_shaper_ops
> 
> Tested with Sphinx 9.1.0 and Docutils 0.22.4:
>   make SPHINXDIRS=networking htmldocs
> 
>  include/net/net_shaper.h | 17 +++++++++--------
>  1 file changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
> index 05cb625b0fe54..a2eb616a19fd0 100644
> --- a/include/net/net_shaper.h
> +++ b/include/net/net_shaper.h
> @@ -73,20 +73,21 @@ struct net_shaper {
>   * Each shaper is uniquely identified within the device with a 'handle'
>   * comprising the shaper scope and a scope-specific id.
>   *
> - * Driver ops vs uAPI
> - * ------------------
> + * **Driver ops vs uAPI**
> + *
>   * Members of the driver ops mirror the Netlink uAPI but driver calls do not
>   * map 1:1 to user calls. Drivers need to be careful when assuming that calls
>   * 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)
>   *
> - * Implicit creation
> - * -----------------
> + * - @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**
> + *
>   * Shapers are created implicitly, meaning that @set and @group operations
>   * are called both for existing and new shapers. The driver has to infer
>   * whether the operation is an update or a creation by tracking the handles.
> 
> base-commit: 3205699d79f262412c1be7fc1c04066610d3cd52

Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Randy Dunlap]

On 8/14/26 10:14 AM, Jakub Kicinski wrote:
> Adding the missing CC of linux-doc
> 
> On Thu, 13 Aug 2026 21:21:31 +0200 Karl Mehltretter wrote:
>> Everything from the "Driver ops vs uAPI" heading onward is dropped from
>> the rendered net_shaper_ops documentation. Older Docutils versions do so
>> silently, while Docutils 0.22 reports the nested headings and adjacent
>> list as invalid.
> 
> Isn't this a problem in kernel-doc extraction / how we embed it for
> rendering? Heading are quite useful and IMHO far more natural to use.
> My understanding was that kdoc should be able to use basic ReST
> formatting.
> 
> Ack on the list indent fix
> 
>> Use bold labels and correct the list indentation.
>>
>> Fixes: 16812d9674d4 ("net_shaper: remove incorrect comment about group leaves")
>> Fixes: 26bc4cfb1737 ("net_shaper: clarify the kernel API / comments")
> 
> This is a doc patch, please don't sprinkle Fixes tag on patches which
> don't fix bugs.
> 

I would prefer to also see the actual warning messages in the patch description,
but that's up to the maintainer(s).  (or just one of them would be OK)

Documentation/networking/kapi:107: ../include/net/net_shaper.h:75: ERROR: A level 3 section cannot be used here.

Driver ops vs uAPI
------------------

Established title styles: =/= = -

The parent of level 3 sections cannot be reached. The parser is at section level 3 but the current node has only 0 parent section(s).
One reason may be a high level section used in a directive that parses its content into a base node not attached to the document
(up to Docutils 0.21, these sections were silently dropped). [docutils]
Documentation/networking/kapi:107: ../include/net/net_shaper.h:82: ERROR: Unexpected indentation. [docutils]


I don't know of another reasonable solution for this (although I'm no expert
on ReST), so

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

Thanks.

>> Assisted-by: Codex:gpt-5.6-sol
>> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
>> ---
>> The omission is visible in the current linux-next generated documentation:
>> https://www.kernel.org/doc/html/next/networking/kapi.html#c.net_shaper_ops
>>
>> Tested with Sphinx 9.1.0 and Docutils 0.22.4:
>>   make SPHINXDIRS=networking htmldocs
>>
>>  include/net/net_shaper.h | 17 +++++++++--------
>>  1 file changed, 9 insertions(+), 8 deletions(-)
>>
>> diff --git a/include/net/net_shaper.h b/include/net/net_shaper.h
>> index 05cb625b0fe54..a2eb616a19fd0 100644
>> --- a/include/net/net_shaper.h
>> +++ b/include/net/net_shaper.h
>> @@ -73,20 +73,21 @@ struct net_shaper {
>>   * Each shaper is uniquely identified within the device with a 'handle'
>>   * comprising the shaper scope and a scope-specific id.
>>   *
>> - * Driver ops vs uAPI
>> - * ------------------
>> + * **Driver ops vs uAPI**
>> + *
>>   * Members of the driver ops mirror the Netlink uAPI but driver calls do not
>>   * map 1:1 to user calls. Drivers need to be careful when assuming that calls
>>   * 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)
>>   *
>> - * Implicit creation
>> - * -----------------
>> + * - @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**
>> + *
>>   * Shapers are created implicitly, meaning that @set and @group operations
>>   * are called both for existing and new shapers. The driver has to infer
>>   * whether the operation is an update or a creation by tracking the handles.
>>
>> base-commit: 3205699d79f262412c1be7fc1c04066610d3cd52
> 
> 

Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Karl Mehltretter]

On Fri, Aug 14, 2026 at 12:04:05PM +0100, Randy Dunlap wrote:
> On 8/14/26 10:14 AM, Jakub Kicinski wrote:
> > 
> > Isn't this a problem in kernel-doc extraction / how we embed it for
> > rendering? Heading are quite useful and IMHO far more natural to use.
> > My understanding was that kdoc should be able to use basic ReST
> > formatting.
> > 
> > Ack on the list indent fix
> > 
> 
> I don't know of another reasonable solution for this (although I'm no expert
> on ReST), so
> 

Yes, this is a problem in how Documentation/sphinx/kerneldoc.py embeds
kernel-doc output. It parses generated content into a detached node while
retaining the surrounding title hierarchy.

The key kerneldoc.py change is replacing the parser call:

-            self.state.nested_parse(result, 0, node, match_titles=1)
+            nested_parse_with_titles(self.state, result, node)

This preserves the headings.

I tested the networking documentation with Sphinx 9.1.0 and Docutils
0.21.2 and 0.22.4, and a full htmldocs build with Docutils 0.22.4. The
full build produced only unrelated existing warnings.

I can send this as a two-patch v2, with the list correction first.

Thanks,
Karl

Re: [PATCH net-next] net_shaper: fix net_shaper_ops kernel-doc

[Randy Dunlap]

On 8/14/26 3:49 PM, Karl Mehltretter wrote:
> On Fri, Aug 14, 2026 at 12:04:05PM +0100, Randy Dunlap wrote:
>> On 8/14/26 10:14 AM, Jakub Kicinski wrote:
>>>
>>> Isn't this a problem in kernel-doc extraction / how we embed it for
>>> rendering? Heading are quite useful and IMHO far more natural to use.
>>> My understanding was that kdoc should be able to use basic ReST
>>> formatting.
>>>
>>> Ack on the list indent fix
>>>
>>
>> I don't know of another reasonable solution for this (although I'm no expert
>> on ReST), so
>>
> 
> Yes, this is a problem in how Documentation/sphinx/kerneldoc.py embeds
> kernel-doc output. It parses generated content into a detached node while
> retaining the surrounding title hierarchy.
> 
> The key kerneldoc.py change is replacing the parser call:
> 
> -            self.state.nested_parse(result, 0, node, match_titles=1)
> +            nested_parse_with_titles(self.state, result, node)
> 
> This preserves the headings.
> 
> I tested the networking documentation with Sphinx 9.1.0 and Docutils
> 0.21.2 and 0.22.4, and a full htmldocs build with Docutils 0.22.4. The
> full build produced only unrelated existing warnings.
> 
> I can send this as a two-patch v2, with the list correction first.

Please do so.
Thanks.

-- 
~Randy