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

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

[Matthieu Baerts (NGI0)]

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'.

Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
---
Note: this patch can be applied without conflicts on top of net-next and
docs-next. To be honest, it is not clear to me who is responsible for
applying it :)
---
 tools/net/ynl/pyynl/lib/doc_generator.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl/lib/doc_generator.py
index 403abf1a2edaac6936d0e9db0623cd3e07aaad8e..3a16b8eb01ca0cf61a5983d3bd6a866e04c75844 100644
--- a/tools/net/ynl/pyynl/lib/doc_generator.py
+++ b/tools/net/ynl/pyynl/lib/doc_generator.py
@@ -289,6 +289,10 @@ class YnlDocGenerator:
         for entry in entries:
             lines.append(self.fmt.rst_section(namespace, 'attribute-set',
                                               entry["name"]))
+
+            if "doc" in entry:
+                lines.append(self.fmt.rst_paragraph(entry["doc"], 0) + "\n")
+
             for attr in entry["attributes"]:
                 if LINE_STR in attr:
                     lines.append(self.fmt.rst_lineno(attr[LINE_STR]))

---
base-commit: deb105f49879dd50d595f7f55207d6e74dec34e6
change-id: 20250910-net-next-ynl-attr-doc-rst-b61532634245

Best regards,
-- 
Matthieu Baerts (NGI0) <matttbe@kernel.org>

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

[Donald Hunter]

"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.

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]

> Signed-off-by: Matthieu Baerts (NGI0) <matttbe@kernel.org>
> ---
> Note: this patch can be applied without conflicts on top of net-next and
> docs-next. To be honest, it is not clear to me who is responsible for
> applying it :)
> ---
>  tools/net/ynl/pyynl/lib/doc_generator.py | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl/lib/doc_generator.py
> index 403abf1a2edaac6936d0e9db0623cd3e07aaad8e..3a16b8eb01ca0cf61a5983d3bd6a866e04c75844 100644
> --- a/tools/net/ynl/pyynl/lib/doc_generator.py
> +++ b/tools/net/ynl/pyynl/lib/doc_generator.py
> @@ -289,6 +289,10 @@ class YnlDocGenerator:
>          for entry in entries:
>              lines.append(self.fmt.rst_section(namespace, 'attribute-set',
>                                                entry["name"]))
> +
> +            if "doc" in entry:
> +                lines.append(self.fmt.rst_paragraph(entry["doc"], 0) + "\n")
> +
>              for attr in entry["attributes"]:
>                  if LINE_STR in attr:
>                      lines.append(self.fmt.rst_lineno(attr[LINE_STR]))
>
> ---
> base-commit: deb105f49879dd50d595f7f55207d6e74dec34e6
> change-id: 20250910-net-next-ynl-attr-doc-rst-b61532634245
>
> Best regards,

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

[Matthieu Baerts]

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.

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

[Donald Hunter]

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

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

[Matthieu Baerts]

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.