doc: _extensions: add :zephyr:board-catalog: role

doc/_extensions/zephyr/domain/__init__.py

@@ -27,6 +27,7 @@
 - ``:zephyr:code-sample:`` - References a code sample.
 - ``:zephyr:code-sample-category:`` - References a code sample category.
 - ``:zephyr:board:`` - References a board.
+- ``:zephyr:board-catalog:`` - References the board catalog page, optionally with filter parameters.
 
 """
 
@@ -749,9 +750,21 @@ class BoardCatalogDirective(SphinxDirective):
 
     def run(self):
         if self.env.app.builder.format == "html":
-            self.env.domaindata["zephyr"]["has_board_catalog"][self.env.docname] = True
-
             domain_data = self.env.domaindata["zephyr"]
+
+            # Check if a board catalog already exists
+            existing_catalog = domain_data["board_catalog_docname"]
+            if existing_catalog is not None:
+                logger.error(
+                    f"Only one board catalog is allowed per documentation build. "
+                    f"Found in both {existing_catalog} and {self.env.docname}.",
+                    location=(self.env.docname, self.lineno),
+                )
+                return []
+
+            # Cache the docname containing the board catalog
+            domain_data["board_catalog_docname"] = self.env.docname
+
             renderer = SphinxRenderer([TEMPLATES_DIR])
             rendered = renderer.render(
                 "board-catalog.html",
@@ -1138,6 +1151,7 @@ class ZephyrDomain(Domain):
         "code-sample": XRefRole(innernodeclass=nodes.inline, warn_dangling=True),
         "code-sample-category": XRefRole(innernodeclass=nodes.inline, warn_dangling=True),
         "board": XRefRole(innernodeclass=nodes.inline, warn_dangling=True),
+        "board-catalog": XRefRole(innernodeclass=nodes.inline, warn_dangling=True),
     }
 
     directives = {
@@ -1162,7 +1176,7 @@ class ZephyrDomain(Domain):
         "code-samples-categories-tree": Node("samples"),
         # keep track of documents containing special directives
         "has_code_sample_listing": {},  # docname -> bool
-        "has_board_catalog": {},  # docname -> bool
+        "board_catalog_docname": None,  # docname of the one page containing the board catalog
         "has_board": {},  # docname -> bool
     }
 
@@ -1182,7 +1196,8 @@ def clear_doc(self, docname: str) -> None:
         # TODO clean up the anytree as well
 
         self.data["has_code_sample_listing"].pop(docname, None)
-        self.data["has_board_catalog"].pop(docname, None)
+        if self.data["board_catalog_docname"] == docname:
+            self.data["board_catalog_docname"] = None
         self.data["has_board"].pop(docname, None)
 
     def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
@@ -1213,11 +1228,12 @@ def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
             self.data["has_code_sample_listing"][docname] = otherdata[
                 "has_code_sample_listing"
             ].get(docname, False)
-            self.data["has_board_catalog"][docname] = otherdata["has_board_catalog"].get(
-                docname, False
-            )
             self.data["has_board"][docname] = otherdata["has_board"].get(docname, False)
 
+        # Merge board catalog docname - there should only be one
+        if otherdata["board_catalog_docname"] is not None:
+            self.data["board_catalog_docname"] = otherdata["board_catalog_docname"]
+
     def get_objects(self):
         for _, code_sample in self.data["code-samples"].items():
             yield (
@@ -1266,6 +1282,23 @@ def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode):
             elem = self.data["code-samples-categories"].get(target)
         elif type == "board":
             elem = self.data["boards"].get(target)
+        elif type == "board-catalog":
+            catalog_docname = self.data["board_catalog_docname"]
+            if catalog_docname is None:
+                return None
+
+            anchor = target if target.startswith("#") else ""
+            if not node.get("refexplicit"):
+                contnode = [nodes.Text("Board Catalog")]
+
+            return make_refnode(
+                builder,
+                fromdocname,
+                catalog_docname,
+                anchor.lstrip("#") if anchor else None,
+                contnode,
+                None,
+            )
         else:
             return
 
@@ -1366,7 +1399,7 @@ def install_static_assets_as_needed(
         app.add_css_file("css/codesample-livesearch.css")
         app.add_js_file("js/codesample-livesearch.js")
 
-    if app.env.domaindata["zephyr"]["has_board_catalog"].get(pagename, False):
+    if app.env.domaindata["zephyr"]["board_catalog_docname"] == pagename:
         app.add_css_file("css/board-catalog.css")
         app.add_js_file("js/board-catalog.js")
 

doc/contribute/documentation/guidelines.rst

@@ -1293,6 +1293,28 @@ Boards
    This directive is used to generate a catalog of Zephyr-supported boards that can be used to
    quickly browse the list of all supported boards and filter them according to various criteria.
 
+.. rst:role:: zephyr:board-catalog
+
+   This role is used to reference the board catalog page, optionally with filter parameters.
+   For example::
+
+      Check out :zephyr:board-catalog:`` for more information.
+
+   Will render as:
+
+      Check out :zephyr:board-catalog:`` for more information.
+
+   This role can be used exactly like the built-in :rst:role:`ref` role, i.e. you may provide a
+   custom link text. For example::
+
+      Check out the :zephyr:board-catalog:`boards using this compatible <#compatibles=ti,hdc2080>`
+      for more information.
+
+   Will render as:
+
+      Check out the :zephyr:board-catalog:`boards using this compatible <#compatibles=ti,hdc2080>`
+      for more information.
+
 .. rst:directive:: .. zephyr:board-supported-hw::
 
    This directive is used to show supported hardware features for all the targets of the board