From 1801ecc8eebac3d3cf8842430a1456a6ed3fb294 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Thu, 27 Feb 2025 12:21:39 +0100 Subject: [PATCH] doc: extensions: Navigate to DTS entries from supported hardware list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the gen_board_catalog.py logic to capture filename/lineno for each devicetree node. Use that info in the supported hardware list to create clickable elements that directly take the user to the corresponding line in the devicetree file on Github. Signed-off-by: Benjamin Cabé --- doc/_extensions/zephyr/domain/__init__.py | 70 ++++++++++++------- .../zephyr/domain/static/css/board.css | 2 +- doc/_scripts/gen_boards_catalog.py | 21 ++++-- 3 files changed, 62 insertions(+), 31 deletions(-) diff --git a/doc/_extensions/zephyr/domain/__init__.py b/doc/_extensions/zephyr/domain/__init__.py index 77454a36f31d..50d666d864ee 100644 --- a/doc/_extensions/zephyr/domain/__init__.py +++ b/doc/_extensions/zephyr/domain/__init__.py @@ -36,7 +36,7 @@ from anytree import ChildResolverError, Node, PreOrderIter, Resolver, search from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import directives, roles from docutils.statemachine import StringList from sphinx import addnodes from sphinx.application import Sphinx @@ -798,17 +798,20 @@ def run(self): return result_nodes html_contents = """
-
-
on-chip
-
Feature integrated in the SoC.
-
on-board
-
Feature present on the board.
-
2
-
Number of instances of the feature that are present and enabled.
-
2
-
Number of instances of the feature that are present but initially disabled.
+
+
on-chip / on-board
+
+ Feature integrated in the SoC / present on the board. +
+
2 / 2
+
+ Number of instances that are enabled / disabled.
+ Click on the label to see the first instance of this feature in DTS source files. +
vnd,foo
-
Compatible string for the Devicetree binding matching the feature. +
+ Compatible string for the Devicetree binding matching the feature.
Click on the link to checkout the binding documentation.
@@ -861,7 +864,7 @@ def feature_sort_key(feature): for i, (key, value) in enumerate(items): row = nodes.row() - if value.get("disabled_count", 0) > 0 and value.get("okay_count", 0) == 0: + if value.get("disabled_nodes", []) and not value.get("okay_nodes", []): row["classes"].append("disabled") # TYPE column @@ -902,22 +905,39 @@ def feature_sort_key(feature): desc_para += nodes.Text(value["description"]) # Add count indicators for okay and not-okay instances - okay_count = value.get("okay_count", 0) - disabled_count = value.get("disabled_count", 0) + okay_nodes = value.get("okay_nodes", []) + disabled_nodes = value.get("disabled_nodes", []) - if okay_count > 0: - okay_count_indicator = nodes.inline( - classes=["count", "okay-count"], - text=str(okay_count), - ) - desc_para += okay_count_indicator + role_fn, _ = roles.role( + "zephyr_file", self.state_machine.language, self.lineno, self.state.reporter + ) + + def create_count_indicator(nodes_list, class_type, role_function=role_fn): + if not nodes_list: + return None + + count = len(nodes_list) - if disabled_count > 0: - disabled_count_indicator = nodes.inline( - classes=["count", "disabled-count"], - text=str(disabled_count), + if role_function is None: + return nodes.inline( + classes=["count", f"{class_type}-count"], text=str(count) + ) + + # Create a reference to the first node in the list + first_node = nodes_list[0] + file_ref = f"{count} <{first_node['filename']}#L{first_node['lineno']}>" + + role_nodes, _ = role_function( + "zephyr_file", file_ref, file_ref, self.lineno, self.state.inliner ) - desc_para += disabled_count_indicator + + count_node = role_nodes[0] + count_node["classes"] = ["count", f"{class_type}-count"] + + return count_node + + desc_para += create_count_indicator(okay_nodes, "okay") + desc_para += create_count_indicator(disabled_nodes, "disabled") desc_entry += desc_para row += desc_entry diff --git a/doc/_extensions/zephyr/domain/static/css/board.css b/doc/_extensions/zephyr/domain/static/css/board.css index 1224067bfff2..5a50c419fb03 100644 --- a/doc/_extensions/zephyr/domain/static/css/board.css +++ b/doc/_extensions/zephyr/domain/static/css/board.css @@ -83,7 +83,6 @@ .legend { font-size: 0.9em; - max-width: 600px; border-radius: 6px; margin: auto; @@ -179,6 +178,7 @@ font-size: 0.7em; font-weight: 600; margin-left: 4px; + padding-right: 6px !important; &::before { content: "×"; diff --git a/doc/_scripts/gen_boards_catalog.py b/doc/_scripts/gen_boards_catalog.py index 681b7a735b6c..f2dbbfc20db9 100755 --- a/doc/_scripts/gen_boards_catalog.py +++ b/doc/_scripts/gen_boards_catalog.py @@ -271,6 +271,7 @@ def get_catalog(generate_hw_features=False): description = DeviceTreeUtils.get_cached_description(node) filename = node.filename + lineno = node.lineno locations = set() if Path(filename).is_relative_to(ZEPHYR_BASE): filename = Path(filename).relative_to(ZEPHYR_BASE) @@ -284,15 +285,25 @@ def get_catalog(generate_hw_features=False): ) if existing_feature: locations.update(existing_feature["locations"]) - key = "okay_count" if node.status == "okay" else "disabled_count" - existing_feature[key] = existing_feature.get(key, 0) + 1 + node_info = {"filename": str(filename), "lineno": lineno} + if node.status == "okay": + existing_feature.setdefault("okay_nodes", []).append(node_info) + else: + existing_feature.setdefault("disabled_nodes", []).append(node_info) else: - key = "okay_count" if node.status == "okay" else "disabled_count" - target_features.setdefault(binding_type, {})[node.matching_compat] = { + node_info = {"filename": str(filename), "lineno": lineno} + feature_data = { "description": description, "locations": locations, - key: 1 } + if node.status == "okay": + feature_data["okay_nodes"] = [node_info] + feature_data["disabled_nodes"] = [] + else: + feature_data["okay_nodes"] = [] + feature_data["disabled_nodes"] = [node_info] + + target_features.setdefault(binding_type, {})[node.matching_compat] = feature_data # Store features for this specific target supported_features[board_target] = target_features