michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: zephyr_domain: Cross reference relevant API in code samples

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

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2024-08-16 12:23:38 +02:00 • committed by Anas Nashif
commit b3ae323add
1 changed files with 30 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

31
doc/_extensions/zephyr/domain.py
View file

@ -88,8 +88,11 @@ class ConvertCodeSampleNode(SphinxTransform):
""" """
Transforms a `CodeSampleNode` into a `nodes.section` named after the code sample name. 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. 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 parent = node.parent
siblings_to_move = [] siblings_to_move = []
@ -111,6 +114,31 @@ class ConvertCodeSampleNode(SphinxTransform):
for sibling in siblings_to_move: for sibling in siblings_to_move:
parent.remove(sibling) 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 # Set sample description as the meta description of the document for improved SEO
meta_description = nodes.meta() meta_description = nodes.meta()
meta_description["name"] = "description" meta_description["name"] = "description"
@ -231,6 +259,7 @@ class CodeSampleDirective(Directive):
code_sample_node = CodeSampleNode() code_sample_node = CodeSampleNode()
code_sample_node["id"] = code_sample_id code_sample_node["id"] = code_sample_id
code_sample_node["name"] = name code_sample_node["name"] = name
code_sample_node["relevant-api"] = relevant_api_list
code_sample_node += description_node code_sample_node += description_node
return [code_sample_node] return [code_sample_node]