Add alternative text parameter for kpm_iframe directive

docs/source/_extensions/kpm_plugin.py

@@ -13,32 +13,36 @@
 from sphinx.writers.latex import LaTeXTranslator
 
 KPM_PATH = "_static/kpm/index.html"
+DEFAULT_ALT_TEXT = "An interactive KPM frame, where you can explore the block design for this section, is available here in the HTML version of this documentation."
 
 
 class KPMNode(nodes.container):
     def __init__(
         self,
+        *,
         depth: int,
-        preview: bool,
-        spec_ref: Optional[str],
-        graph_ref: Optional[str],
-        height: Optional[str],
+        preview: Optional[bool] = None,
+        spec: Optional[str] = None,
+        dataflow: Optional[str] = None,
+        height: Optional[str] = None,
+        alt: Optional[str] = None,
     ) -> None:
         # we're leveraging the builtin download_reference node
         # to automatically move necessary files from sources
         # into the build directory and have a path to them
         spec_node = graph_node = None
-        if spec_ref:
-            spec_node = download_reference("", "", reftarget=spec_ref, disabled=True)
-        if graph_ref:
-            graph_node = download_reference("", "", reftarget=graph_ref, disabled=True)
+        if spec:
+            spec_node = download_reference("", "", reftarget=spec, disabled=True)
+        if dataflow:
+            graph_node = download_reference("", "", reftarget=dataflow, disabled=True)
 
-        super().__init__("", *(node for node in (spec_node, graph_node) if node))
+        super().__init__("", *(node for node in (spec_node, graph_node) if node), self_ref=self)
         self.spec_node = spec_node
         self.graph_node = graph_node
         self.rel_pfx = "../" * depth
         self.preview = preview
         self.height = height
+        self.alt = alt if alt is not None else DEFAULT_ALT_TEXT
 
     def _node_to_target(self, node: download_reference) -> str:
         if "filename" in node:
@@ -71,14 +75,14 @@ def visit_html(trans: HTML5Translator, node: KPMNode):
         )
 
     @staticmethod
-    def visit_latex(trans: LaTeXTranslator, _: KPMNode):
+    def visit_latex(trans: LaTeXTranslator, node: KPMNode):
+        node = node.attributes["self_ref"]
         trans.body.append(
-            r"""
-\begin{sphinxadmonition}{warning}{Note:}
+            rf"""
+\begin{{sphinxadmonition}}{{warning}}{{Note:}}
 \sphinxAtStartPar
-An interactive KPM frame, where you can explore the block design for this section,
-is available here in the HTML version of this documentation.
-\end{sphinxadmonition}"""
+{node.alt}
+\end{{sphinxadmonition}}"""
         )
 
     @staticmethod
@@ -87,18 +91,10 @@ def depart_node(*_):
 
 
 class KPMDirective(SphinxDirective):
-    option_spec = {"spec": path, "dataflow": path, "preview": bool, "height": str}
+    option_spec = {"spec": path, "dataflow": path, "preview": bool, "height": str, "alt": str}
 
     def run(self) -> list[nodes.Node]:
-        return [
-            KPMNode(
-                self.env.docname.count("/"),
-                self.options.get("preview", False),
-                self.options.get("spec"),
-                self.options.get("dataflow"),
-                self.options.get("height"),
-            )
-        ]
+        return [KPMNode(depth=self.env.docname.count("/"), **self.options)]
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

docs/source/developers_guide/inline_kpm_howto.md

@@ -10,6 +10,7 @@ It is possible to use the `kpm_iframe` Sphinx directive to embed KPM directly in
 :dataflow: <KPM dataflow .json file URI>
 :preview: <a boolean value specifying whether this KPM should be started in preview mode>
 :height: <a string css height property that sets the `height` of iframe>
+:alt: <a custom alternative text used in the PDF documentation instead of the default one>
 ```
 ````
 
@@ -22,6 +23,11 @@ All parameters of this directive are optional.
 
 ### Use remote specification
 
+:::{note}
+The graph below is supposed to be empty.
+It doesn't load a dataflow, only a specification that provides IP-cores to the Nodes browser on the sidebar.
+:::
+
 ```{kpm_iframe}
 :spec: https://raw.githubusercontent.com/antmicro/topwrap/main/tests/data/data_kpm/examples/hdmi/specification_hdmi.json
 ```
@@ -41,3 +47,15 @@ All parameters of this directive are optional.
 :dataflow: ../../../tests/data/data_kpm/examples/hierarchy/dataflow_hierarchy.json
 :preview: true
 ```
+
+### Use custom alt text
+
+:::{note}
+The alternative text is visible instead of the iframe in the PDF version of this documentation.
+:::
+
+```{kpm_iframe}
+:spec: ../../../tests/data/data_kpm/examples/hierarchy/specification_hierarchy.json
+:dataflow: https://raw.githubusercontent.com/antmicro/topwrap/refs/heads/main/tests/data/data_kpm/examples/hierarchy/dataflow_hierarchy.json
+:alt: This diagram showcases the block design of the "hierarchy" example
+```