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