* [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs
@ 2024-03-29 13:50 Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 1/3] doc: netlink: Change generated docs to limit TOC to depth 3 Donald Hunter
` (3 more replies)
0 siblings, 4 replies; 5+ messages in thread
From: Donald Hunter @ 2024-03-29 13:50 UTC (permalink / raw)
To: netdev, Jakub Kicinski, David S. Miller, Eric Dumazet,
Paolo Abeni, Jiri Pirko, Breno Leitao, Alessandro Marcolini
Cc: donald.hunter, Donald Hunter
Extend ynl-gen-rst to generate hyperlinks to definitions, attribute sets
and sub-messages from all the places that reference them.
v1 -> v2
- Eliminate 'family' global variable
- Fix whitespace between functions
Donald Hunter (3):
doc: netlink: Change generated docs to limit TOC to depth 3
doc: netlink: Add hyperlinks to generated Netlink docs
doc: netlink: Update tc spec with missing definitions
Documentation/netlink/specs/tc.yaml | 51 ++++++++++++++++++++++++
tools/net/ynl/ynl-gen-rst.py | 62 ++++++++++++++++++++---------
2 files changed, 94 insertions(+), 19 deletions(-)
--
2.44.0
^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH net-next v2 1/3] doc: netlink: Change generated docs to limit TOC to depth 3
2024-03-29 13:50 [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs Donald Hunter
@ 2024-03-29 13:50 ` Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 2/3] doc: netlink: Add hyperlinks to generated Netlink docs Donald Hunter
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2024-03-29 13:50 UTC (permalink / raw)
To: netdev, Jakub Kicinski, David S. Miller, Eric Dumazet,
Paolo Abeni, Jiri Pirko, Breno Leitao, Alessandro Marcolini
Cc: donald.hunter, Donald Hunter
The tables of contents in the generated Netlink docs include individual
attribute definitions. This can make the contents exceedingly long and
repeats a lot of what is on the rest of the pages. See for example:
https://docs.kernel.org/networking/netlink_spec/tc.html
Add a depth limit to the contents directive in generated .rst files to
limit the contents depth to 3 levels. This reduces the contents to:
- Family
- Summary
- Operations
- op-one
- op-two
- ...
- Definitions
- struct-one
- struct-two
- enum-one
- ...
- Attribute sets
- attrs-one
- attrs-two
- ...
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Reviewed-by: Breno Leitao <leitao@debian.org>
---
tools/net/ynl/ynl-gen-rst.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py
index 927407b3efb3..5825a8b3bfb4 100755
--- a/tools/net/ynl/ynl-gen-rst.py
+++ b/tools/net/ynl/ynl-gen-rst.py
@@ -291,7 +291,7 @@ def parse_yaml(obj: Dict[str, Any]) -> str:
title = f"Family ``{obj['name']}`` netlink specification"
lines.append(rst_title(title))
- lines.append(rst_paragraph(".. contents::\n"))
+ lines.append(rst_paragraph(".. contents:: :depth: 3\n"))
if "doc" in obj:
lines.append(rst_subtitle("Summary"))
--
2.44.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH net-next v2 2/3] doc: netlink: Add hyperlinks to generated Netlink docs
2024-03-29 13:50 [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 1/3] doc: netlink: Change generated docs to limit TOC to depth 3 Donald Hunter
@ 2024-03-29 13:50 ` Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 3/3] doc: netlink: Update tc spec with missing definitions Donald Hunter
2024-04-02 4:30 ` [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2024-03-29 13:50 UTC (permalink / raw)
To: netdev, Jakub Kicinski, David S. Miller, Eric Dumazet,
Paolo Abeni, Jiri Pirko, Breno Leitao, Alessandro Marcolini
Cc: donald.hunter, Donald Hunter
Update ynl-gen-rst to generate hyperlinks to definitions, attribute
sets and sub-messages from all the places that reference them.
Note that there is a single label namespace for all of the kernel docs.
Hyperlinks within a single netlink doc need to be qualified by the
family name to avoid collisions.
The label format is 'family-type-name' which gives, for example,
'rt-link-attribute-set-link-attrs' as the link id.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
---
tools/net/ynl/ynl-gen-rst.py | 60 +++++++++++++++++++++++++-----------
1 file changed, 42 insertions(+), 18 deletions(-)
diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py
index 5825a8b3bfb4..657e881d2ea4 100755
--- a/tools/net/ynl/ynl-gen-rst.py
+++ b/tools/net/ynl/ynl-gen-rst.py
@@ -82,9 +82,9 @@ def rst_subsubsection(title: str) -> str:
return f"{title}\n" + "~" * len(title)
-def rst_section(title: str) -> str:
+def rst_section(namespace: str, prefix: str, title: str) -> str:
"""Add a section to the document"""
- return f"\n{title}\n" + "=" * len(title)
+ return f".. _{namespace}-{prefix}-{title}:\n\n{title}\n" + "=" * len(title)
def rst_subtitle(title: str) -> str:
@@ -102,6 +102,17 @@ def rst_list_inline(list_: List[str], level: int = 0) -> str:
return headroom(level) + "[" + ", ".join(inline(i) for i in list_) + "]"
+def rst_ref(namespace: str, prefix: str, name: str) -> str:
+ """Add a hyperlink to the document"""
+ mappings = {'enum': 'definition',
+ 'fixed-header': 'definition',
+ 'nested-attributes': 'attribute-set',
+ 'struct': 'definition'}
+ if prefix in mappings:
+ prefix = mappings[prefix]
+ return f":ref:`{namespace}-{prefix}-{name}`"
+
+
def rst_header() -> str:
"""The headers for all the auto generated RST files"""
lines = []
@@ -159,20 +170,24 @@ def parse_do_attributes(attrs: Dict[str, Any], level: int = 0) -> str:
return "\n".join(lines)
-def parse_operations(operations: List[Dict[str, Any]]) -> str:
+def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str:
"""Parse operations block"""
preprocessed = ["name", "doc", "title", "do", "dump"]
+ linkable = ["fixed-header", "attribute-set"]
lines = []
for operation in operations:
- lines.append(rst_section(operation["name"]))
+ lines.append(rst_section(namespace, 'operation', operation["name"]))
lines.append(rst_paragraph(sanitize(operation["doc"])) + "\n")
for key in operation.keys():
if key in preprocessed:
# Skip the special fields
continue
- lines.append(rst_fields(key, operation[key], 0))
+ value = operation[key]
+ if key in linkable:
+ value = rst_ref(namespace, key, value)
+ lines.append(rst_fields(key, value, 0))
if "do" in operation:
lines.append(rst_paragraph(":do:", 0))
@@ -212,14 +227,14 @@ def parse_entries(entries: List[Dict[str, Any]], level: int) -> str:
return "\n".join(lines)
-def parse_definitions(defs: Dict[str, Any]) -> str:
+def parse_definitions(defs: Dict[str, Any], namespace: str) -> str:
"""Parse definitions section"""
preprocessed = ["name", "entries", "members"]
ignored = ["render-max"] # This is not printed
lines = []
for definition in defs:
- lines.append(rst_section(definition["name"]))
+ lines.append(rst_section(namespace, 'definition', definition["name"]))
for k in definition.keys():
if k in preprocessed + ignored:
continue
@@ -237,14 +252,15 @@ def parse_definitions(defs: Dict[str, Any]) -> str:
return "\n".join(lines)
-def parse_attr_sets(entries: List[Dict[str, Any]]) -> str:
+def parse_attr_sets(entries: List[Dict[str, Any]], namespace: str) -> str:
"""Parse attribute from attribute-set"""
preprocessed = ["name", "type"]
+ linkable = ["enum", "nested-attributes", "struct", "sub-message"]
ignored = ["checks"]
lines = []
for entry in entries:
- lines.append(rst_section(entry["name"]))
+ lines.append(rst_section(namespace, 'attribute-set', entry["name"]))
for attr in entry["attributes"]:
type_ = attr.get("type")
attr_line = attr["name"]
@@ -257,25 +273,31 @@ def parse_attr_sets(entries: List[Dict[str, Any]]) -> str:
for k in attr.keys():
if k in preprocessed + ignored:
continue
- lines.append(rst_fields(k, sanitize(attr[k]), 0))
+ if k in linkable:
+ value = rst_ref(namespace, k, attr[k])
+ else:
+ value = sanitize(attr[k])
+ lines.append(rst_fields(k, value, 0))
lines.append("\n")
return "\n".join(lines)
-def parse_sub_messages(entries: List[Dict[str, Any]]) -> str:
+def parse_sub_messages(entries: List[Dict[str, Any]], namespace: str) -> str:
"""Parse sub-message definitions"""
lines = []
for entry in entries:
- lines.append(rst_section(entry["name"]))
+ lines.append(rst_section(namespace, 'sub-message', entry["name"]))
for fmt in entry["formats"]:
value = fmt["value"]
lines.append(rst_bullet(bold(value)))
for attr in ['fixed-header', 'attribute-set']:
if attr in fmt:
- lines.append(rst_fields(attr, fmt[attr], 1))
+ lines.append(rst_fields(attr,
+ rst_ref(namespace, attr, fmt[attr]),
+ 1))
lines.append("\n")
return "\n".join(lines)
@@ -289,7 +311,9 @@ def parse_yaml(obj: Dict[str, Any]) -> str:
lines.append(rst_header())
- title = f"Family ``{obj['name']}`` netlink specification"
+ family = obj['name']
+
+ title = f"Family ``{family}`` netlink specification"
lines.append(rst_title(title))
lines.append(rst_paragraph(".. contents:: :depth: 3\n"))
@@ -300,7 +324,7 @@ def parse_yaml(obj: Dict[str, Any]) -> str:
# Operations
if "operations" in obj:
lines.append(rst_subtitle("Operations"))
- lines.append(parse_operations(obj["operations"]["list"]))
+ lines.append(parse_operations(obj["operations"]["list"], family))
# Multicast groups
if "mcast-groups" in obj:
@@ -310,17 +334,17 @@ def parse_yaml(obj: Dict[str, Any]) -> str:
# Definitions
if "definitions" in obj:
lines.append(rst_subtitle("Definitions"))
- lines.append(parse_definitions(obj["definitions"]))
+ lines.append(parse_definitions(obj["definitions"], family))
# Attributes set
if "attribute-sets" in obj:
lines.append(rst_subtitle("Attribute sets"))
- lines.append(parse_attr_sets(obj["attribute-sets"]))
+ lines.append(parse_attr_sets(obj["attribute-sets"], family))
# Sub-messages
if "sub-messages" in obj:
lines.append(rst_subtitle("Sub-messages"))
- lines.append(parse_sub_messages(obj["sub-messages"]))
+ lines.append(parse_sub_messages(obj["sub-messages"], family))
return "\n".join(lines)
--
2.44.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH net-next v2 3/3] doc: netlink: Update tc spec with missing definitions
2024-03-29 13:50 [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 1/3] doc: netlink: Change generated docs to limit TOC to depth 3 Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 2/3] doc: netlink: Add hyperlinks to generated Netlink docs Donald Hunter
@ 2024-03-29 13:50 ` Donald Hunter
2024-04-02 4:30 ` [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: Donald Hunter @ 2024-03-29 13:50 UTC (permalink / raw)
To: netdev, Jakub Kicinski, David S. Miller, Eric Dumazet,
Paolo Abeni, Jiri Pirko, Breno Leitao, Alessandro Marcolini
Cc: donald.hunter, Donald Hunter
The tc spec referenced tc-u32-mark and tc-act-police-attrs but did not
define them. The missing definitions were discovered when building the
docs with generated hyperlinks because the hyperlink target labels were
missing.
Add definitions for tc-u32-mark and tc-act-police-attrs.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
---
Documentation/netlink/specs/tc.yaml | 51 +++++++++++++++++++++++++++++
1 file changed, 51 insertions(+)
diff --git a/Documentation/netlink/specs/tc.yaml b/Documentation/netlink/specs/tc.yaml
index 324fa182cd14..6068c105c5ee 100644
--- a/Documentation/netlink/specs/tc.yaml
+++ b/Documentation/netlink/specs/tc.yaml
@@ -1099,6 +1099,19 @@ definitions:
-
name: offmask
type: s32
+ -
+ name: tc-u32-mark
+ type: struct
+ members:
+ -
+ name: val
+ type: u32
+ -
+ name: mask
+ type: u32
+ -
+ name: success
+ type: u32
-
name: tc-u32-sel
type: struct
@@ -1774,6 +1787,44 @@ attribute-sets:
-
name: key-ex
type: binary
+ -
+ name: tc-act-police-attrs
+ attributes:
+ -
+ name: tbf
+ type: binary
+ struct: tc-police
+ -
+ name: rate
+ type: binary # TODO
+ -
+ name: peakrate
+ type: binary # TODO
+ -
+ name: avrate
+ type: u32
+ -
+ name: result
+ type: u32
+ -
+ name: tm
+ type: binary
+ struct: tcf-t
+ -
+ name: pad
+ type: pad
+ -
+ name: rate64
+ type: u64
+ -
+ name: peakrate64
+ type: u64
+ -
+ name: pktrate64
+ type: u64
+ -
+ name: pktburst64
+ type: u64
-
name: tc-act-simple-attrs
attributes:
--
2.44.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs
2024-03-29 13:50 [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs Donald Hunter
` (2 preceding siblings ...)
2024-03-29 13:50 ` [PATCH net-next v2 3/3] doc: netlink: Update tc spec with missing definitions Donald Hunter
@ 2024-04-02 4:30 ` patchwork-bot+netdevbpf
3 siblings, 0 replies; 5+ messages in thread
From: patchwork-bot+netdevbpf @ 2024-04-02 4:30 UTC (permalink / raw)
To: Donald Hunter
Cc: netdev, kuba, davem, edumazet, pabeni, jiri, leitao,
alessandromarcolini99, donald.hunter
Hello:
This series was applied to netdev/net-next.git (main)
by Jakub Kicinski <kuba@kernel.org>:
On Fri, 29 Mar 2024 13:50:18 +0000 you wrote:
> Extend ynl-gen-rst to generate hyperlinks to definitions, attribute sets
> and sub-messages from all the places that reference them.
>
> v1 -> v2
> - Eliminate 'family' global variable
> - Fix whitespace between functions
>
> [...]
Here is the summary with links:
- [net-next,v2,1/3] doc: netlink: Change generated docs to limit TOC to depth 3
https://git.kernel.org/netdev/net-next/c/4cc1730a90fc
- [net-next,v2,2/3] doc: netlink: Add hyperlinks to generated Netlink docs
https://git.kernel.org/netdev/net-next/c/8c1b74a26d96
- [net-next,v2,3/3] doc: netlink: Update tc spec with missing definitions
https://git.kernel.org/netdev/net-next/c/2dddf8aaf67f
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-04-02 4:30 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-03-29 13:50 [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 1/3] doc: netlink: Change generated docs to limit TOC to depth 3 Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 2/3] doc: netlink: Add hyperlinks to generated Netlink docs Donald Hunter
2024-03-29 13:50 ` [PATCH net-next v2 3/3] doc: netlink: Update tc spec with missing definitions Donald Hunter
2024-04-02 4:30 ` [PATCH net-next v2 0/3] doc: netlink: Add hyperlinks to generated docs patchwork-bot+netdevbpf
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.