[nrf noup] doc: extensions: doxybridge: add support for multiple projects

Modify the extension so that multiple Doxygen projects can be
referenced. While not required in upstream Zephyr, other users
downstream may require support for this feature.

Signed-off-by: Gerard Marull-Paretas <[email protected]>
(cherry picked from commit 779b0c7b910976538f045b1b85d8bcdb061464d2)

Author: gmarull

doc/_extensions/zephyr/doxybridge.py

@@ -4,22 +4,20 @@
 SPDX-License-Identifier: Apache-2.0
 """
 
-import os
-from typing import Any, Dict
-
 import concurrent.futures
+import os
+from typing import Any
 
+import doxmlparser
 from docutils import nodes
-
+from docutils.parsers.rst import directives
+from doxmlparser.compound import DoxCompoundKind, DoxMemberKind
 from sphinx import addnodes
 from sphinx.application import Sphinx
+from sphinx.domains.c import CXRefRole
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
-from sphinx.domains.c import CXRefRole
-
-import doxmlparser
-from doxmlparser.compound import DoxCompoundKind, DoxMemberKind
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +35,9 @@ class DoxygenGroupDirective(SphinxDirective):
     has_content = False
     required_arguments = 1
     optional_arguments = 0
+    option_spec = {
+        "project": directives.unchanged,
+    }
 
     def run(self):
 
@@ -51,6 +52,7 @@ def run(self):
             reftype="group",
             reftarget=self.arguments[0],
             refwarn=True,
+            project=self.options.get("project")
         )
         group_xref += nodes.Text(self.arguments[0])
         title_signode += group_xref
@@ -76,28 +78,40 @@ def run(self, **kwargs: Any) -> None:
             if reftype in ("member", "data"):
                 reftype = "var"
 
-            entry = self.app.env.doxybridge_cache.get(reftype)
-            if not entry:
-                continue
+            found_name = None
+            found_id = None
+            for name in self.app.config.doxybridge_projects:
+                entry = self.app.env.doxybridge_cache[name].get(reftype)
+                if not entry:
+                    continue
 
-            reftarget = node.get("reftarget").replace(".", "::").rstrip("()")
-            id = entry.get(reftarget)
-            if not id:
-                if reftype == "func":
-                    # macros are sometimes referenced as functions, so try that
-                    id = self.app.env.doxybridge_cache.get("macro").get(reftarget)
-                    if not id:
+                reftarget = node.get("reftarget").replace(".", "::").rstrip("()")
+                id = entry.get(reftarget)
+                if not id:
+                    if reftype == "func":
+                        # macros are sometimes referenced as functions, so try that
+                        id = self.app.env.doxybridge_cache[name].get("macro").get(reftarget)
+                        if not id:
+                            continue
+                    else:
                         continue
-                else:
-                    continue
+
+                found_name = name
+                found_id = id
+                break
+
+            if not found_name or not found_id:
+                continue
 
             if reftype in ("struct", "union", "group"):
                 doxygen_target = f"{id}.html"
             else:
-                split = id.split("_")
+                split = found_id.split("_")
                 doxygen_target = f"{'_'.join(split[:-1])}.html#{split[-1][1:]}"
 
-            doxygen_target = str(self.app.config.doxybridge_dir) + "/html/" + doxygen_target
+            doxygen_target = (
+                str(self.app.config.doxybridge_projects[found_name]) + "/html/" + doxygen_target
+            )
 
             doc_dir = os.path.dirname(self.document.get("source"))
             doc_dest = os.path.join(
@@ -112,7 +126,7 @@ def run(self, **kwargs: Any) -> None:
 
             if reftype == "group":
                 refnode["classes"].append("doxygroup")
-                title = self.app.env.doxybridge_group_titles.get(reftarget, "group")
+                title = self.app.env.doxybridge_group_titles[found_name].get(reftarget, "group")
                 refnode[0] = nodes.Text(title)
 
             node.replace_self([refnode])
@@ -154,7 +168,7 @@ def parse_sections(compounddef):
     return cache
 
 
-def parse_compound(inDirName, baseName) -> Dict:
+def parse_compound(inDirName, baseName) -> dict:
     rootObj = doxmlparser.compound.parse(inDirName + "/" + baseName + ".xml", True)
     cache = {}
     group_titles = {}
@@ -181,7 +195,7 @@ def parse_compound(inDirName, baseName) -> Dict:
     return cache, group_titles
 
 
-def parse_index(app: Sphinx, inDirName):
+def parse_index(app: Sphinx, name, inDirName):
     rootObj = doxmlparser.index.parse(inDirName + "/index.xml", True)
     compounds = rootObj.get_compound()
 
@@ -193,33 +207,40 @@ def parse_index(app: Sphinx, inDirName):
         for future in concurrent.futures.as_completed(futures):
             cache, group_titles = future.result()
             for kind, data in cache.items():
-                app.env.doxybridge_cache.setdefault(kind, {}).update(data)
-            app.env.doxybridge_group_titles.update(group_titles)
+                app.env.doxybridge_cache[name].setdefault(kind, {}).update(data)
+            app.env.doxybridge_group_titles[name].update(group_titles)
 
 
 def doxygen_parse(app: Sphinx) -> None:
-    if not app.env.doxygen_input_changed:
-        return
-
-    app.env.doxybridge_cache = {
-        "macro": {},
-        "var": {},
-        "type": {},
-        "enum": {},
-        "enumerator": {},
-        "func": {},
-        "union": {},
-        "struct": {},
-        "group": {},
-    }
+    if not hasattr(app.env, "doxybridge_cache"):
+        app.env.doxybridge_cache = dict()
+
+    if not hasattr(app.env, "doxybridge_group_titles"):
+        app.env.doxybridge_group_titles = dict()
+
+    for name, path in app.config.doxybridge_projects.items():
+        if name in app.env.doxygen_input_changed and not app.env.doxygen_input_changed[name]:
+            return
+
+        app.env.doxybridge_cache[name] = {
+            "macro": {},
+            "var": {},
+            "type": {},
+            "enum": {},
+            "enumerator": {},
+            "func": {},
+            "union": {},
+            "struct": {},
+            "group": {},
+        }
 
-    app.env.doxybridge_group_titles = {}
+        app.env.doxybridge_group_titles[name] = dict()
 
-    parse_index(app, str(app.config.doxybridge_dir / "xml"))
+        parse_index(app, name, str(path / "xml"))
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
-    app.add_config_value("doxybridge_dir", None, "env")
+def setup(app: Sphinx) -> dict[str, Any]:
+    app.add_config_value("doxybridge_projects", None, "env")
 
     app.add_directive("doxygengroup", DoxygenGroupDirective)
 

doc/conf.py

@@ -256,7 +256,7 @@
 
 # -- Options for zephyr.doxybridge plugin ---------------------------------
 
-doxybridge_dir = doxyrunner_projects["zephyr"]["outdir"]
+doxybridge_projects = {"zephyr": doxyrunner_projects["zephyr"]["outdir"]}
 
 # -- Options for html_redirect plugin -------------------------------------