netdev - Re: [PATCH] Documentation: Document the Netlink spec

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]

Date: Mon, 6 Nov 2023 14:51:11 -0800
From: Jakub Kicinski <kuba@...nel.org>
To: Breno Leitao <leitao@...ian.org>
Cc: corbet@....net, linux-doc@...r.kernel.org, netdev@...r.kernel.org,
 pabeni@...hat.com, edumazet@...gle.com
Subject: Re: [PATCH] Documentation: Document the Netlink spec

On Fri,  3 Nov 2023 06:56:22 -0700 Breno Leitao wrote:
> This is a Sphinx extension that parses the Netlink YAML spec files
> (Documentation/netlink/specs/), and generates a rst file to be
> displayed into Documentation pages.
> 
> Create a new Documentation/networking/netlink_spec page, and a sub-page
> for each Netlink spec that needs to be documented, such as ethtool,
> devlink, netdev, etc.
> 
> Create a Sphinx directive extension that reads the YAML spec
> (located under Documentation/netlink/specs), parses it and returns a RST
> string that is inserted where the Sphinx directive was called.

> +=======================================
> +Family ``fou`` netlink specification
> +=======================================

nit: bad length of the ==== marker lines

> +def parse_attributes_set(entries: List[Dict[str, Any]]) -> str:

I'd rename to parse_attr_sets (plural sets).

> +    """Parse attribute from attribute-set"""
> +    preprocessed = ["name", "type"]
> +    ignored = ["checks"]
> +    lines = []
> +
> +    for entry in entries:
> +        lines.append(rst_bullet(bold(entry["name"])))

This would be better as subsubtitle.

> +        for attr in entry["attributes"]:
> +            type_ = attr.get("type")
> +            attr_line = bold(attr["name"])
> +            if type_:
> +                # Add the attribute type in the same line
> +                attr_line += f" ({inline(type_)})"
> +
> +            lines.append(rst_bullet(attr_line, 2))

And this actually, probably also a sub^3-title, because we'll want to
link to the specific attributes sooner or later. And linking to bullet
points isn't a thing (AFAIU?)