Filter breathe xml input folder

... from existing folders of doxgen build target.

Author: SebSparrowHawk

bazel/rules/rules_score/private/sphinx_module.bzl

@@ -19,6 +19,39 @@ load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
 load("@rules_python//sphinxdocs/private:sphinx_docs_library_info.bzl", "SphinxDocsLibraryInfo")
 load("//bazel/rules/rules_score:providers.bzl", "SphinxModuleInfo", "SphinxNeedsInfo")
 
+# Delimiter used to encode filter_execpath parameters into a single extra_opts string.
+_FILTER_EXECPATH_DELIM = "@@FILTER_EXECPATH@@"
+
+def filter_execpath(flag, label, filter_pattern):
+    """Construct an extra_opts entry that filters execpaths and rewrites them with the relocated target prefix.
+
+    When used in extra_opts of sphinx_module, the rule implementation will:
+    1. Expand $(execpaths <label>) to get all output paths
+    2. Filter for the path containing <filter_pattern>
+    3. Rewrite the path to include the target's relocated prefix
+       (e.g. bazel-out/.../bin/<package>/<name>/<original_path>)
+
+    Example usage in BUILD:
+        load("@score_tooling//bazel/rules/rules_score:rules_score.bzl", "filter_execpath", "sphinx_module")
+
+        sphinx_module(
+            name = "sphinx_doc",
+            extra_opts = [
+                filter_execpath("-Dbreathe_projects.com", "//docs/sphinx:doxygen_xml", "doxygen_build/xml"),
+            ],
+            ...
+        )
+
+    Args:
+        flag: The Sphinx -D flag prefix (e.g. "-Dbreathe_projects.com")
+        label: The Bazel label whose execpaths to expand (e.g. "//docs/sphinx:doxygen_xml")
+        filter_pattern: Substring to match when filtering the execpaths (e.g. "doxygen_build/xml")
+
+    Returns:
+        A specially formatted string that the sphinx_module rule will process.
+    """
+    return _FILTER_EXECPATH_DELIM.join([flag, str(label), filter_pattern])
+
 def _create_config_py(ctx):
     """Get or generate the conf.py configuration file.
 
@@ -119,11 +152,55 @@ def _score_html_impl(ctx):
     # Expand location references in extra_opts and collect as sphinx arguments.
     # targets must include all labels referenced via $(location ...) / $(execpaths ...).
     extra_opts_targets = ctx.attr.srcs + ctx.attr.docs_library_deps
+    source_prefix = ctx.label.name
+
     for opt in ctx.attr.extra_opts:
-        expanded = ctx.expand_location(opt, targets = extra_opts_targets)
-        print("???????? expanded opts location: ", expanded)
-        args.add(expanded)
-        run_args.append(expanded)
+        if _FILTER_EXECPATH_DELIM in opt:
+            # Process filter_execpath() encoded strings:
+            # Format: flag@@FILTER_EXECPATH@@label@@FILTER_EXECPATH@@filter_pattern
+            parts = opt.split(_FILTER_EXECPATH_DELIM)
+            flag = parts[0]
+            label_str = parts[1]
+            filter_pattern = parts[2]
+
+            # Expand execpaths for the referenced label
+            expanded = ctx.expand_location("$(execpaths " + label_str + ")", targets = extra_opts_targets)
+            expanded_paths = expanded.split(" ")
+
+            # Filter for the path matching the filter pattern
+            matched_path = None
+            for p in expanded_paths:
+                if filter_pattern in p:
+                    matched_path = p
+                    break
+
+            if not matched_path:
+                fail("filter_execpath: no path matching '{}' found in execpaths of {}. Paths: {}".format(
+                    filter_pattern,
+                    label_str,
+                    expanded,
+                ))
+
+            # Extract the path suffix after "/bin/" — this is the original path relative
+            # to the output base. Since _relocate() symlinks source files under
+            # <source_prefix>/<original_path>, the relocated file lives at
+            # <source_dir>/<suffix_part> where source_dir is the Sphinx source directory.
+            # Breathe resolves breathe_projects paths relative to source_dir (app.srcdir),
+            # so we must return just the suffix_part.
+            bin_marker = "/bin/"
+            bin_idx = matched_path.find(bin_marker)
+            if bin_idx >= 0:
+                suffix_part = matched_path[bin_idx + len(bin_marker):]
+            else:
+                suffix_part = matched_path
+
+            expanded_opt = flag + "=" + suffix_part
+        else:
+            # Standard extra_opts: expand locations and pass through
+            expanded_opt = ctx.expand_location(opt, targets = extra_opts_targets)
+
+        args.add(expanded_opt)
+        run_args.append(expanded_opt)
 
     # Collect all transitive dependencies with deduplication
     modules = []
@@ -150,7 +227,6 @@ def _score_html_impl(ctx):
         content = json.encode_indent(needs_external_needs, indent = "  "),
     )
 
-    source_prefix = ctx.label.name
     sphinx_source_files = []
 
     # Materialize a file under the `_sources` dir
@@ -281,8 +357,8 @@ _score_html = rule(
             doc = "Submodule symbols.needs targets for this module.",
         ),
         extra_opts = attr.string_list(
-                    doc = "Additional options to pass onto Sphinx. These are added after " +
-                          "other options, but before the source/output args.",
+            doc = "Additional options to pass onto Sphinx. These are added after " +
+                  "other options, but before the source/output args.",
         ),
     ),
     toolchains = ["//bazel/rules/rules_score:toolchain_type"],

bazel/rules/rules_score/rules_score.bzl

@@ -48,6 +48,7 @@ load(
 )
 load(
     "//bazel/rules/rules_score/private:sphinx_module.bzl",
+    _filter_execpath = "filter_execpath",
     _sphinx_module = "sphinx_module",
 )
 load(
@@ -65,6 +66,7 @@ component_requirements = _component_requirements
 dependability_analysis = _dependability_analysis
 feature_requirements = _feature_requirements
 fmea = _fmea
+filter_execpath = _filter_execpath
 sphinx_module = _sphinx_module
 unit = _unit
 unit_design = _unit_design

bazel/rules/rules_score/src/sphinx_html_merge.py

@@ -178,11 +178,6 @@ def main():
         help="Dependency HTML directory in format NAME:PATH",
     )
 
-    parser.add_argument(
-        "-Dbreathe_projects",
-        help="Override Breathe projects mapping (e.g., -Dbreathe_projects='{\"com\": \"path/to/xml\"}')",
-    )
-
     args = parser.parse_args()
 
     # Parse dependencies

bazel/rules/rules_score/src/sphinx_wrapper.py

@@ -110,7 +110,9 @@ def validate_arguments(args: argparse.Namespace) -> None:
         raise ValueError(f"Index file does not exist: {args.index_file}")
 
 
-def build_sphinx_arguments(args: argparse.Namespace, extra_args: List[str] = None) -> List[str]:
+def build_sphinx_arguments(
+    args: argparse.Namespace, extra_args: List[str] = None
+) -> List[str]:
     """
     Build the argument list for Sphinx.