Re: [PATCH net-next v2 01/11] tools/net/ynl-gen-rst: Use bullet lists for attribute-set entries

[Donald Hunter <donald.hunter@gmail.com>]

Jakub Kicinski <kuba@kernel.org> writes:

> On Mon, 11 Dec 2023 16:40:29 +0000 Donald Hunter wrote:
>> The generated .rst for attribute-sets currently uses a sub-sub-heading
>> for each individual attribute. Change this to use a bullet list the
>> attributes in an attribute-set. It is more compact and readable.
>
> This is on purpose, we want to be able to link to the attributes.
> And AFAIU we can only link to headings.
>
> The documentation for attrs is currently a bit sparse so the docs 
> end up looking awkward. But that's a problem with people not writing
> enough doc comments, not with the render, innit? :(

Okay, then I think we need to try and improve the formatting. Currently
h3 and h4 both have font-size: 130% and the attribute headings get
rendered in bold so they stand out more than the attribute-set headings
they are under. I suggest:

 - Removing the bold markup from the attribute headings
 - Changing h4 to font-size: 110% in sphinx-static/custom.css

That improves things a bit but I feel that the attribute-set headings
still get a bit lost. Not sure if there is anything we can do about
that. The devlink spec is a fairly extreme example because it has a lot
of subset definitions that look especially bleak.