Re: [PATCH] Documentation: Document the Netlink spec

[Jakub Kicinski <kuba@kernel.org>]

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