Jakub Kicinski <kuba@xxxxxxxxxx> 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.
