| Message ID | 20231211164039.83034-2-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | tools/net/ynl: Add 'sub-message' support to ynl | expand |
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? :(
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.
On Tue, 12 Dec 2023 11:27:18 +0000 Donald Hunter wrote: > 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 SG, but probably as a separate change directed at linux-doc tree? > 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. Right.. nobody bothers documenting in the old families. netdev is probably the example to look at when deciding on what looks okay, hopefully it's closer to what new/documented families would look like.
diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py index b6292109e236..a1d046c60512 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py @@ -240,7 +240,7 @@ def parse_attr_sets(entries: List[Dict[str, Any]]) -> str: # Add the attribute type in the same line attr_line += f" ({inline(type_)})" - lines.append(rst_subsubsection(attr_line)) + lines.append(rst_bullet(attr_line)) for k in attr.keys(): if k in preprocessed + ignored:
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. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- tools/net/ynl/ynl-gen-rst.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)