kartben · kartben · Feb 28, 2025 · Feb 4, 2025 · Jan 19, 2025 · Feb 27, 2025
diff --git a/boards/cypress/cy8ckit_062_ble/doc/index.rst b/boards/cypress/cy8ckit_062_ble/doc/index.rst
@@ -1,7 +1,4 @@
-.. _cy8ckit_062_ble:
-
-INFINEON PSOC 63 BLE Pioneer Kit
-################################
+.. zephyr:board:: cy8ckit_062_ble
 
 Overview
 ********
@@ -30,10 +27,6 @@ enabling you to emulate a BLE host on your computer.
 The Cortex-M0+ is a primary core on the board's SoC. It starts first and
 enables the CM4 core.
 
-.. image:: img/cy8ckit-062-ble.jpg
-     :align: center
-     :alt: CY8CKIT_062_BLE
-
 1. Battery charging indicator (LED6)
 2. USB PD output voltage availability indicator (LED7)
 3. KitProg2 USB Type-C connector (J10)

diff --git a/boards/cypress/cy8ckit_062_wifi_bt/doc/index.rst b/boards/cypress/cy8ckit_062_wifi_bt/doc/index.rst
@@ -1,7 +1,4 @@
-.. _cy8ckit_062_wifi_bt:
-
-INFINEON PSOC 6 WiFi-BT Pioneer Kit
-###################################
+.. zephyr:board:: cy8ckit_062_wifi_bt
 
 Overview
 ********
@@ -23,10 +20,6 @@ The PSOC 6 WiFi-BT Pioneer board offers compatibility with Arduino shields.
 The Cortex-M0+ is a primary core on the board's SoC. It starts first and
 enables the CM4 core.
 
-.. image:: img/cy8ckit_062_wifi_bt_m0.jpg
-     :align: center
-     :alt: CY8CKIT_062_WIFI_BT
-
 1. USB PD output voltage availability indicator (LED7)
 2. Battery charging indicator (LED6)
 3. KitProg2 USB Type-C connector (J10)

diff --git a/boards/ene/kb1200_evb/doc/index.rst b/boards/ene/kb1200_evb/doc/index.rst
@@ -1,7 +1,4 @@
-.. _ene_kb1200_evb:
-
-ENE KB1200_EVB
-##############
+.. zephyr:board:: kb1200_evb
 
 Overview
 ********

diff --git a/boards/enjoydigital/litex_vexriscv/doc/index.rst b/boards/enjoydigital/litex_vexriscv/doc/index.rst
@@ -1,7 +1,4 @@
-.. _litex-vexriscv:
-
-LiteX VexRiscv
-##############
+.. zephyr:board:: litex_vexriscv
 
 LiteX VexRiscv is an example of a system on a chip (SoC) that consists of
 a `VexRiscv processor <https://github.com/SpinalHDL/VexRiscv>`_
@@ -20,10 +17,6 @@ LiteX VexRiscv SoC implementation generated for the
 <https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists>`_
 or `SDI-MIPI Video Converter <https://github.com/antmicro/sdi-mipi-video-converter>`_.
 
-.. image:: img/litex_vexriscv.jpg
-   :align: center
-   :alt: LiteX VexRiscv on Digilent Arty 35T Board
-
 LiteX is based on
 `Migen <https://m-labs.hk/gateware/migen/>`_/`MiSoC SoC builder <https://github.com/m-labs/misoc>`_
 and provides ready-made system components such as buses, streams, interconnects,

diff --git a/boards/ite/it82xx2_evb/doc/index.rst b/boards/ite/it82xx2_evb/doc/index.rst
@@ -1,7 +1,4 @@
-.. _it82xx2_evb:
-
-ITE IT82XX2 series
-######################
+.. zephyr:board:: it82xx2_evb
 
 Overview
 ********

diff --git a/boards/ite/it8xxx2_evb/doc/index.rst b/boards/ite/it8xxx2_evb/doc/index.rst
@@ -1,7 +1,4 @@
-.. _it8xxx2_evb:
-
-ITE IT8XXX2 series
-######################
+.. zephyr:board:: it8xxx2_evb
 
 Overview
 ********

diff --git a/boards/lowrisc/opentitan_earlgrey/doc/index.rst b/boards/lowrisc/opentitan_earlgrey/doc/index.rst
@@ -1,7 +1,4 @@
-.. _opentitan_earlgrey:
-
-OpenTitan Earl Grey
-###################
+.. zephyr:board:: opentitan_earlgrey
 
 Overview
 ********

diff --git a/boards/rakwireless/rak5010/doc/index.rst b/boards/rakwireless/rak5010/doc/index.rst
@@ -1,8 +1,5 @@
 .. zephyr:board:: rak5010
 
-RAK5010
-#######
-
 Overview
 ********
 

diff --git a/boards/seagate/faze/doc/index.rst b/boards/seagate/faze/doc/index.rst
@@ -1,7 +1,4 @@
-.. _faze:
-
-Seagate FireCuda Gaming SSD (FaZe) board
-########################################
+.. zephyr:board:: faze
 
 Overview
 ********
@@ -14,10 +11,6 @@ through I2C and GPIOs.
 
 This Zephyr port is running on the NXP LPC11U67 MCU.
 
-.. image:: firecuda-gaming-ssd.jpg
-   :align: center
-   :alt: Seagate FireCuda Gaming SSD
-
 Hardware
 ********
 

diff --git a/boards/seagate/legend/doc/index.rst b/boards/seagate/legend/doc/index.rst
@@ -1,7 +1,4 @@
-.. _legend:
-
-Legend
-######
+.. zephyr:board:: legend
 
 Overview
 ********

diff --git a/boards/up-bridge-the-gap/up_squared/doc/index.rst b/boards/up-bridge-the-gap/up_squared/doc/index.rst
@@ -1,7 +1,4 @@
-.. _up_squared:
-
-UP Squared
-##########
+.. zephyr:board:: up_squared
 
 Overview
 ********
@@ -11,12 +8,6 @@ performance and low power consumption. It features the latest Intel |reg| Apollo
 Lake Celeron |trade| and Pentium |trade| Processors with only 4W of Scenario Design Power and
 a powerful and flexible Intel |reg| FPGA Altera MAX 10 onboard.
 
-.. figure:: img/up_squared.jpg
-   :align: center
-   :alt: UP Squared
-
-   Up Squared (Credit: https://up-board.org)
-
 This board configuration enables kernel support for the `UP Squared`_ board.
 
 .. note::

diff --git a/boards/up-bridge-the-gap/up_squared_pro_7000/doc/up_squared_pro_7000.rst b/boards/up-bridge-the-gap/up_squared_pro_7000/doc/up_squared_pro_7000.rst
@@ -1,9 +1,4 @@
-:orphan:
-
-.. _up_squared_pro_7000_board:
-
-UP Squared Pro 7000
-###################
+.. zephyr:board:: up_squared_pro_7000
 
 Overview
 ********

diff --git a/doc/LICENSING.rst b/doc/LICENSING.rst
@@ -59,8 +59,8 @@ ENE KB1200_EVB Board OpenOCD Configuration
 ------------------------------------------
 
 * *Licensing:* `GPLv2 License`_
-* *Impact:* This file is used by `OpenOCD`_ when programming and debugging the :ref:`ene_kb1200_evb`
-  board. It is never linked into the firmware.
+* *Impact:* This file is used by `OpenOCD`_ when programming and debugging the
+  :zephyr:board:`kb1200_evb` board. It is never linked into the firmware.
 * *Files:*
 
   * :zephyr_file:`boards/ene/kb1200_evb/support/openocd.cfg`

diff --git 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
@@ -797,55 +797,33 @@ def run(self):
             result_nodes.append(note)
             return result_nodes
 
-        # Add the note before any tables
-        note = nodes.admonition(classes=["legend"])
-        note += nodes.title(text="Table Legend", classes=["note"])
-
-        legend = nodes.definition_list(classes=["supported-hardware field-list"])
-
-        def add_legend_item(legend_list, term_text, term_classes, definition_text):
-            dl_item = nodes.definition_list_item()
-            dt = nodes.term()
-            dt += nodes.inline("", term_text, classes=term_classes)
-            dd = nodes.definition()
-            dd += nodes.Text(definition_text)
-            dl_item += dt
-            dl_item += dd
-            legend_list += dl_item
-
-        add_legend_item(
-            legend, "on-chip", ["location-chip", "onchip"], "Feature integrated in the SoC."
-        )
-        add_legend_item(
-            legend, "on-board", ["location-chip", "onboard"], "Feature present on the board."
-        )
-        add_legend_item(
-            legend,
-            "2",
-            ["count", "okay-count"],
-            "Number of instances of the feature that are present and enabled.",
-        )
-        add_legend_item(
-            legend,
-            "2",
-            ["count", "disabled-count"],
-            "Number of instances of the feature that are present but initially disabled.",
-        )
-
-        dl_item = nodes.definition_list_item()
-        dt = nodes.term()
-        dt += nodes.literal(text="vnd,foo")
-        dd = nodes.definition()
-        dd += nodes.Text(
-            "Compatible string for the Devicetree binding matching the feature. "
-            "Click on the link to checkout the binding documentation."
-        )
-        dl_item += dt
-        dl_item += dd
-        legend += dl_item
-
-        note += legend
-        result_nodes.append(note)
+        html_contents = """<div class="legend admonition">
+  <dl class="supported-hardware field-list">
+    <dt>
+      <span class="location-chip onchip">on-chip</span> /
+      <span class="location-chip onboard">on-board</span>
+    </dt>
+    <dd>
+      Feature integrated in the SoC / present on the board.
+    </dd>
+    <dt>
+      <span class="count okay-count">2</span> /
+      <span class="count disabled-count">2</span>
+    </dt>
+    <dd>
+      Number of instances that are enabled / disabled. <br/>
+      Click on the label to see the first instance of this feature in the board/SoC DTS files.
+    </dd>
+    <dt>
+      <code class="docutils literal notranslate"><span class="pre">vnd,foo</span></code>
+    </dt>
+    <dd>
+      Compatible string for the Devicetree binding matching the feature. <br/>
+      Click on the link to view the binding documentation.
+    </dd>
+  </dl>
+</div>"""
+        result_nodes.append(nodes.raw("", html_contents, format="html"))
 
         for target, features in sorted(supported_features.items()):
             if not features:
@@ -893,7 +871,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
@@ -934,22 +912,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 role_function is None:
+                            return nodes.inline(
+                                classes=["count", f"{class_type}-count"], text=str(count)
+                            )
 
-                    if disabled_count > 0:
-                        disabled_count_indicator = nodes.inline(
-                            classes=["count", "disabled-count"],
-                            text=str(disabled_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
@@ -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: "×";