From c697f515b6390b17e4a54a6f93aedf27133929c5 Mon Sep 17 00:00:00 2001 From: Donald Hunter Date: Tue, 28 May 2024 15:06:49 +0100 Subject: [PATCH 1/4] doc: netlink: Fix generated .rst for multi-line docs Fix the newline replacement in ynl-gen-rst.py to put spaces between concatenated lines. This fixes the broken doc string formatting. See the dpll docs for an example of broken concatenation: https://docs.kernel.org/6.9/networking/netlink_spec/dpll.html#lock-status Signed-off-by: Donald Hunter Link: https://lore.kernel.org/r/20240528140652.9445-2-donald.hunter@gmail.com Signed-off-by: Jakub Kicinski --- 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 657e881d2ea4a..5c7465d6befa0 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py @@ -49,7 +49,7 @@ def inline(text: str) -> str: def sanitize(text: str) -> str: """Remove newlines and multiple spaces""" # This is useful for some fields that are spread across multiple lines - return str(text).replace("\n", "").strip() + return str(text).replace("\n", " ").strip() def rst_fields(key: str, value: str, level: int = 0) -> str: From ebf9004136c76b7b62fe628a4bc88b3e894b4b95 Mon Sep 17 00:00:00 2001 From: Donald Hunter Date: Tue, 28 May 2024 15:06:50 +0100 Subject: [PATCH 2/4] doc: netlink: Don't 'sanitize' op docstrings in generated .rst The doc strings for do/dump ops are emitted as toplevel .rst constructs so they can be multi-line. Pass multi-line text straight through to the .rst to retain any simple formatting from the .yaml This fixes e.g. list formatting for the pin-get docs in dpll.yaml: https://docs.kernel.org/6.9/networking/netlink_spec/dpll.html#pin-get Signed-off-by: Donald Hunter Link: https://lore.kernel.org/r/20240528140652.9445-3-donald.hunter@gmail.com Signed-off-by: Jakub Kicinski --- Documentation/netlink/specs/dpll.yaml | 1 + tools/net/ynl/ynl-gen-rst.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml index 95b0eb1486bf7..94132d30e0e03 100644 --- a/Documentation/netlink/specs/dpll.yaml +++ b/Documentation/netlink/specs/dpll.yaml @@ -479,6 +479,7 @@ operations: name: pin-get doc: | Get list of pins and its attributes. + - dump request without any attributes given - list all the pins in the system - dump request with target dpll - list all the pins registered with diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py index 5c7465d6befa0..1096a71d7867a 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py @@ -178,7 +178,7 @@ def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str: for operation in operations: lines.append(rst_section(namespace, 'operation', operation["name"])) - lines.append(rst_paragraph(sanitize(operation["doc"])) + "\n") + lines.append(rst_paragraph(operation["doc"]) + "\n") for key in operation.keys(): if key in preprocessed: From cb7351ac17862cf8d4e00831ce4aa27f53bda01c Mon Sep 17 00:00:00 2001 From: Donald Hunter Date: Tue, 28 May 2024 15:06:51 +0100 Subject: [PATCH 3/4] doc: netlink: Fix formatting of op flags in generated .rst Generate op flags as an inline list instead of a stringified python value. Signed-off-by: Donald Hunter Link: https://lore.kernel.org/r/20240528140652.9445-4-donald.hunter@gmail.com Signed-off-by: Jakub Kicinski --- tools/net/ynl/ynl-gen-rst.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py index 1096a71d7867a..a957725b20dc5 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py @@ -172,7 +172,7 @@ def parse_do_attributes(attrs: Dict[str, Any], level: int = 0) -> str: def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str: """Parse operations block""" - preprocessed = ["name", "doc", "title", "do", "dump"] + preprocessed = ["name", "doc", "title", "do", "dump", "flags"] linkable = ["fixed-header", "attribute-set"] lines = [] @@ -188,6 +188,8 @@ def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> str: if key in linkable: value = rst_ref(namespace, key, value) lines.append(rst_fields(key, value, 0)) + if 'flags' in operation: + lines.append(rst_fields('flags', rst_list_inline(operation['flags']))) if "do" in operation: lines.append(rst_paragraph(":do:", 0)) From 9104feed4c6454b9a720e7e11047be7e5cd83487 Mon Sep 17 00:00:00 2001 From: Donald Hunter Date: Tue, 28 May 2024 15:06:52 +0100 Subject: [PATCH 4/4] doc: netlink: Fix op pre and post fields in generated .rst The generated .rst has pre and post headings without any values, e.g. here: https://docs.kernel.org/6.9/networking/netlink_spec/dpll.html#device-id-get Emit keys and values in the generated .rst Signed-off-by: Donald Hunter Link: https://lore.kernel.org/r/20240528140652.9445-5-donald.hunter@gmail.com Signed-off-by: Jakub Kicinski --- tools/net/ynl/ynl-gen-rst.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/net/ynl/ynl-gen-rst.py b/tools/net/ynl/ynl-gen-rst.py index a957725b20dc5..6c56d0d726b41 100755 --- a/tools/net/ynl/ynl-gen-rst.py +++ b/tools/net/ynl/ynl-gen-rst.py @@ -156,7 +156,10 @@ def parse_do(do_dict: Dict[str, Any], level: int = 0) -> str: lines = [] for key in do_dict.keys(): lines.append(rst_paragraph(bold(key), level + 1)) - lines.append(parse_do_attributes(do_dict[key], level + 1) + "\n") + if key in ['request', 'reply']: + lines.append(parse_do_attributes(do_dict[key], level + 1) + "\n") + else: + lines.append(headroom(level + 2) + do_dict[key] + "\n") return "\n".join(lines)