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

[Donald Hunter <donald.hunter@gmail.com>]

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.

> 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: >-

Cheers,
Donald