From b3ae323addef719b6c7e7aaaa1d7d8585486a72c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= <benjamin@zephyrproject.org>
Date: Fri, 16 Aug 2024 12:23:38 +0200
Subject: [PATCH] doc: zephyr_domain: Cross reference relevant API in code
 samples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-add references to doxygen at the bottom of Code samples' README
Fixes #77149.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
---
 doc/_extensions/zephyr/domain.py | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/doc/_extensions/zephyr/domain.py b/doc/_extensions/zephyr/domain.py
index 92bb50cfd78..df79951a506 100644
--- a/doc/_extensions/zephyr/domain.py
+++ b/doc/_extensions/zephyr/domain.py
@@ -88,8 +88,11 @@ class ConvertCodeSampleNode(SphinxTransform):
         """
         Transforms a `CodeSampleNode` into a `nodes.section` named after the code sample name.
 
-        Moves all sibling nodes that are after the `CodeSampleNode` in the documement under this new
+        Moves all sibling nodes that are after the `CodeSampleNode` in the document under this new
         section.
+
+        Adds a "See Also" section at the end with links to all relevant APIs as per the samples's
+        `relevant-api` attribute.
         """
         parent = node.parent
         siblings_to_move = []
@@ -111,6 +114,31 @@ class ConvertCodeSampleNode(SphinxTransform):
             for sibling in siblings_to_move:
                 parent.remove(sibling)
 
+            # Add a "See Also" section at the end with links to relevant APIs
+            if node["relevant-api"]:
+                see_also_section = nodes.section(ids=["see-also"])
+                see_also_section += nodes.title(text="See also")
+
+                for api in node["relevant-api"]:
+                    desc_node = addnodes.desc()
+                    desc_node["domain"] = "c"
+                    desc_node["objtype"] = "group"
+
+                    title_signode = addnodes.desc_signature()
+                    api_xref = addnodes.pending_xref(
+                        "",
+                        refdomain="c",
+                        reftype="group",
+                        reftarget=api,
+                        refwarn=True,
+                    )
+                    api_xref += nodes.Text(api)
+                    title_signode += api_xref
+                    desc_node += title_signode
+                    see_also_section += desc_node
+
+                new_section += see_also_section
+
             # Set sample description as the meta description of the document for improved SEO
             meta_description = nodes.meta()
             meta_description["name"] = "description"
@@ -231,6 +259,7 @@ class CodeSampleDirective(Directive):
         code_sample_node = CodeSampleNode()
         code_sample_node["id"] = code_sample_id
         code_sample_node["name"] = name
+        code_sample_node["relevant-api"] = relevant_api_list
         code_sample_node += description_node
 
         return [code_sample_node]