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