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

[Matthieu Baerts <matttbe@kernel.org>]

Hi Donald,

On 11/09/2025 12:44, Donald Hunter wrote:
> "Matthieu Baerts (NGI0)" <matttbe@kernel.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.