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

[Matthieu Baerts <matttbe@kernel.org>]

On 12/09/2025 13:07, Donald Hunter wrote:
> Matthieu Baerts <matttbe@kernel.org> writes:
> 
>> 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?
> 
> Could you add it to a v2 please.

Sure, will do!

>> 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.
> 
> Yeah, those doc: entries look weird to me too. Not sure it's worth
> fixing them up, given that they are valid. Also worth noting that the
> two formats that we should encourage are
> 
>   doc: >-
>     Multi line text that will get folded and
>     stripped, i.e. internal newlines and trailing
>     newlines will be removed.
> 
>   doc: |
>     Multi line text that will be handled literally
>     and clipped, i.e. internal newlines and trailing
>     newline are preserved but additional trailing
>     newlines get removed.
> 
> So if we were to fix up the doc:$ occurrences, then I'd suggest using
> doc: >-

Good point!

If these entries look weird to you too, I will add one patch adding
'>-', at least to push people to "properly" declare future scalar strings.

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