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] [thread-next>] [day] [month] [year] [list]

Message-ID: <m2v7lpuv2w.fsf@gmail.com>
Date: Thu, 11 Sep 2025 11:44:55 +0100
From: Donald Hunter <donald.hunter@...il.com>
To: "Matthieu Baerts (NGI0)" <matttbe@...nel.org>
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

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

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@...nel.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,