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