[nrf fromlist] doc: extensions: doxyrunner: add support for multiple projects

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

Upstream PR #: 82432

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

Author: gmarull

doc/_extensions/zephyr/doxyrunner.py

@@ -28,17 +28,19 @@
 =====================
 
 - ``doxyrunner_doxygen``: Path to the Doxygen binary.
-- ``doxyrunner_doxyfile``: Path to Doxyfile.
-- ``doxyrunner_outdir``: Doxygen build output directory (inserted to
-  ``OUTPUT_DIRECTORY``)
-- ``doxyrunner_outdir_var``: Variable representing the Doxygen build output
-  directory, as used by ``OUTPUT_DIRECTORY``. This can be useful if other
-  Doxygen variables reference to the output directory.
-- ``doxyrunner_fmt``: Flag to indicate if Doxyfile should be formatted.
-- ``doxyrunner_fmt_vars``: Format variables dictionary (name: value).
-- ``doxyrunner_fmt_pattern``: Format pattern.
 - ``doxyrunner_silent``: If Doxygen output should be logged or not. Note that
   this option may not have any effect if ``QUIET`` is set to ``YES``.
+- ``doxyrunner_projects``: Dictionary specifying projects, keys being project
+  name and values a dictionary with the following keys:
+
+  - ``doxyfile``: Path to Doxyfile.
+  - ``outdir``: Doxygen build output directory (inserted to ``OUTPUT_DIRECTORY``)
+  - ``outdir_var``: Variable representing the Doxygen build output directory,
+    as used by ``OUTPUT_DIRECTORY``. This can be useful if other Doxygen
+    variables reference to the output directory.
+  - ``fmt``: Flag to indicate if Doxyfile should be formatted.
+  - ``fmt_vars``: Format variables dictionary (name: value).
+  - ``fmt_pattern``: Format pattern.
 """
 
 import filecmp
@@ -194,7 +196,7 @@ def process_doxyfile(
     return content
 
 
-def doxygen_input_has_changed(env: BuildEnvironment, doxyfile: str) -> bool:
+def doxygen_input_has_changed(env: BuildEnvironment, name, doxyfile: str) -> bool:
     """Check if Doxygen input files have changed.
 
     Args:
@@ -225,12 +227,15 @@ def doxygen_input_has_changed(env: BuildEnvironment, doxyfile: str) -> bool:
                 for p_file in path.glob("**/" + pattern):
                     cache.add(hash_file(p_file))
 
+    if not hasattr(env, "doxyrunner_cache"):
+        env.doxyrunner_cache = dict()
+
     # check if any file has changed
-    if hasattr(env, "doxyrunner_cache") and env.doxyrunner_cache == cache:
+    if env.doxyrunner_cache.get(name) == cache:
         return False
 
     # store current state
-    env.doxyrunner_cache = cache
+    env.doxyrunner_cache[name] = cache
 
     return True
 
@@ -342,53 +347,52 @@ def doxygen_build(app: Sphinx) -> None:
         app: Sphinx application instance.
     """
 
-    if app.config.doxyrunner_outdir:
-        outdir = Path(app.config.doxyrunner_outdir)
-    else:
-        outdir = Path(app.outdir) / "_doxygen"
-
-    outdir.mkdir(exist_ok=True)
-    tmp_outdir = outdir / "tmp"
-
-    logger.info("Preparing Doxyfile...")
-    doxyfile = process_doxyfile(
-        app.config.doxyrunner_doxyfile,
-        tmp_outdir,
-        app.config.doxyrunner_silent,
-        app.config.doxyrunner_fmt,
-        app.config.doxyrunner_fmt_pattern,
-        app.config.doxyrunner_fmt_vars,
-        app.config.doxyrunner_outdir_var,
-    )
+    for name, config in app.config.doxyrunner_projects.items():
+        if config.get("outdir"):
+            outdir = Path(config["outdir"])
+        else:
+            outdir = Path(app.outdir) / "_doxygen" / name
 
-    logger.info("Checking if Doxygen needs to be run...")
-    app.env.doxygen_input_changed = doxygen_input_has_changed(app.env, doxyfile)
-    if not app.env.doxygen_input_changed:
-        logger.info("Doxygen build will be skipped (no changes)!")
-        return
-
-    logger.info("Running Doxygen...")
-    run_doxygen(
-        app.config.doxyrunner_doxygen,
-        doxyfile,
-        app.config.doxyrunner_silent,
-    )
+        outdir.mkdir(exist_ok=True)
+        tmp_outdir = outdir / "tmp"
+
+        logger.info("Preparing Doxyfile...")
+        doxyfile = process_doxyfile(
+            config["doxyfile"],
+            tmp_outdir,
+            app.config.doxyrunner_silent,
+            config.get("fmt", False),
+            config.get("fmt_pattern", "@{}@"),
+            config.get("fmt_vars", {}),
+            config.get("outdir_var"),
+        )
+
+        logger.info(f"Checking if Doxygen needs to be run for {name}...")
+        if not hasattr(app.env, "doxygen_input_changed"):
+            app.env.doxygen_input_changed = dict()
+
+        app.env.doxygen_input_changed[name] = doxygen_input_has_changed(app.env, name, doxyfile)
+        if not app.env.doxygen_input_changed[name]:
+            logger.info(f"Doxygen build for {name} will be skipped (no changes)!")
+            return
+
+        logger.info(f"Running Doxygen for {name}...")
+        run_doxygen(
+            app.config.doxyrunner_doxygen,
+            doxyfile,
+            app.config.doxyrunner_silent,
+        )
 
-    logger.info("Syncing Doxygen output...")
-    sync_doxygen(doxyfile, tmp_outdir, outdir)
+        logger.info(f"Syncing Doxygen output for {name}...")
+        sync_doxygen(doxyfile, tmp_outdir, outdir)
 
-    shutil.rmtree(tmp_outdir)
+        shutil.rmtree(tmp_outdir)
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("doxyrunner_doxygen", "doxygen", "env")
-    app.add_config_value("doxyrunner_doxyfile", None, "env")
-    app.add_config_value("doxyrunner_outdir", None, "env")
-    app.add_config_value("doxyrunner_outdir_var", None, "env")
-    app.add_config_value("doxyrunner_fmt", False, "env")
-    app.add_config_value("doxyrunner_fmt_vars", {}, "env")
-    app.add_config_value("doxyrunner_fmt_pattern", "@{}@", "env")
     app.add_config_value("doxyrunner_silent", True, "")
+    app.add_config_value("doxyrunner_projects", {}, "")
 
     app.connect("builder-inited", doxygen_build)
 

doc/conf.py

@@ -241,15 +241,22 @@
 # -- Options for zephyr.doxyrunner plugin ---------------------------------
 
 doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen")
-doxyrunner_doxyfile = ZEPHYR_BASE / "doc" / "zephyr.doxyfile.in"
-doxyrunner_outdir = ZEPHYR_BUILD / "doxygen"
-doxyrunner_fmt = True
-doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version}
-doxyrunner_outdir_var = "DOXY_OUT"
+doxyrunner_projects = {
+    "zephyr": {
+        "doxyfile": ZEPHYR_BASE / "doc" / "zephyr.doxyfile.in",
+        "outdir": ZEPHYR_BUILD / "doxygen",
+        "fmt": True,
+        "fmt_vars": {
+            "ZEPHYR_BASE": str(ZEPHYR_BASE),
+            "ZEPHYR_VERSION": version,
+        },
+        "outdir_var": "DOXY_OUT",
+    },
+}
 
 # -- Options for zephyr.doxybridge plugin ---------------------------------
 
-doxybridge_dir = doxyrunner_outdir
+doxybridge_dir = doxyrunner_projects["zephyr"]["outdir"]
 
 # -- Options for html_redirect plugin -------------------------------------
 
@@ -348,7 +355,7 @@
 
 # -- Options for zephyr.api_overview --------------------------------------
 
-api_overview_doxygen_out_dir = str(doxyrunner_outdir)
+api_overview_doxygen_out_dir = str(doxyrunner_projects["zephyr"]["outdir"])
 
 def setup(app):
     # theme customizations