linux-kernel - Re: [PATCH net-next] tools: ynl: rst: display attribute-set doc

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <a1f55940-7115-4650-835c-2f1138c5eaa4@kernel.org>
Date: Thu, 11 Sep 2025 18:59:08 +0200
From: Matthieu Baerts <matttbe@...nel.org>
To: Donald Hunter <donald.hunter@...il.com>
Cc: Jonathan Corbet <corbet@....net>, Jakub Kicinski <kuba@...nel.org>,
 "David S. Miller" <davem@...emloft.net>, Eric Dumazet <edumazet@...gle.com>,
 Paolo Abeni <pabeni@...hat.com>, Simon Horman <horms@...nel.org>,
 linux-doc@...r.kernel.org, netdev@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH net-next] tools: ynl: rst: display attribute-set doc

Hi Donald,

On 11/09/2025 12:44, Donald Hunter wrote:
> "Matthieu Baerts (NGI0)" <matttbe@...nel.org> writes:
> 
>> Some attribute-set have a documentation (doc:), but it was not displayed
>> in the RST / HTML version. Such field can be found in ethtool, netdev,
>> tcp_metrics and team YAML files.
>>
>> Only the 'name' and 'attributes' fields from an 'attribute-set' section
>> were parsed. Now the content of the 'doc' field, if available, is added
>> as a new paragraph before listing each attribute. This is similar to
>> what is done when parsing the 'operations'.
> 
> This fix looks good, but exposes the same issue with the team
> attribute-set in team.yaml.

Good catch! I forgot to check why the output was like that before
sending this patch.

> The following patch is sufficient to generate output that sphinx doesn't
> mangle:
> 
> diff --git a/Documentation/netlink/specs/team.yaml b/Documentation/netlink/specs/team.yaml
> index cf02d47d12a4..fae40835386c 100644
> --- a/Documentation/netlink/specs/team.yaml
> +++ b/Documentation/netlink/specs/team.yaml
> @@ -25,7 +25,7 @@ definitions:
>  attribute-sets:
>    -
>      name: team
> -    doc:
> +    doc: |
>        The team nested layout of get/set msg looks like
>            [TEAM_ATTR_LIST_OPTION]
>                [TEAM_ATTR_ITEM_OPTION]
Yes, that's enough to avoid the mangled output in .rst and .html files.

Do you plan to send this patch, or do you prefer if I send it? As part
of another series or do you prefer a v2?

Note that a few .yaml files have the doc definition starting at the next
line, but without this '|' at the end. It looks strange to me to have
the string defined at the next line like that. I was thinking about
sending patches containing modifications created by the following
command, but I see that this way of writing the string value is valid in
YAML.

  $ git grep -l "doc:$" -- Documentation/netlink/specs | \
        xargs sed -i 's/doc:$/doc: |/g'

Except the one with "team", the other ones don't have their output
mangled. So such modifications are probably not needed for the other ones.

Cheers,
Matt
-- 
Sponsored by the NGI0 Core fund.