Introduce extra_opts to handle additional input

E.g. to specify location of breathe projects

Author: SebSparrowHawk

bazel/rules/rules_score/private/sphinx_module.bzl

@@ -113,6 +113,18 @@ def _score_html_impl(ctx):
     Phase 2: Generate HTML with external needs and merge all dependency HTML
     """
 
+    run_args = []  # Copy of the args to forward along to debug runner
+    args = ctx.actions.args()  # Args passed to the action
+
+    # 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
+    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)
+
     # Collect all transitive dependencies with deduplication
     modules = []
     sphinx_toolchain = ctx.toolchains["//bazel/rules/rules_score:toolchain_type"].sphinxinfo
@@ -138,18 +150,6 @@ def _score_html_impl(ctx):
         content = json.encode_indent(needs_external_needs, indent = "  "),
     )
 
-    # Read template and substitute PROJECT_NAME
-    config_file = ctx.actions.declare_file(ctx.label.name + "/conf.py")
-    template = sphinx_toolchain.conf_template.files.to_list()[0]
-
-    ctx.actions.expand_template(
-        template = template,
-        output = config_file,
-        substitutions = {
-            "{PROJECT_NAME}": ctx.label.name.replace("_", " ").title(),
-        },
-    )
-
     source_prefix = ctx.label.name
     sphinx_source_files = []
 
@@ -182,13 +182,6 @@ def _score_html_impl(ctx):
                 new_path = entry.prefix + original.short_path.removeprefix(entry.strip_prefix)
                 _relocate(original, new_path)
 
-    needs_external_needs_json = ctx.actions.declare_file(ctx.label.name + "/needs_external_needs.json")
-
-    ctx.actions.write(
-        output = needs_external_needs_json,
-        content = json.encode_indent(needs_external_needs, indent = "  "),
-    )
-
     config_file = _create_config_py(ctx)
 
     # Sphinx only accepts a single directory to read its doc sources from.
@@ -219,7 +212,7 @@ def _score_html_impl(ctx):
     ctx.actions.run(
         inputs = html_inputs,
         outputs = [sphinx_html_output],
-        arguments = html_args,
+        arguments = html_args + [args],
         progress_message = "Building HTML: %s" % ctx.label.name,
         executable = sphinx_toolchain.sphinx.files_to_run.executable,
         tools = [
@@ -287,6 +280,10 @@ _score_html = rule(
             allow_files = True,
             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.",
+        ),
     ),
     toolchains = ["//bazel/rules/rules_score:toolchain_type"],
 )
@@ -303,6 +300,7 @@ def sphinx_module(
         docs_library_deps = [],
         sphinx = Label("//bazel/rules/rules_score:score_build"),
         strip_prefix = "",
+        extra_opts = [],
         testonly = False,
         visibility = ["//visibility:public"]):
     """Build a Sphinx module with transitive HTML dependencies.
@@ -323,6 +321,9 @@ def sphinx_module(
                     source files. e.g., given `//sphinxdocs/docs:foo.md`, stripping `docs/` makes
                     Sphinx see `foo.md` in its generated source directory. If not
                     specified, then {any}`native.package_name` is used.
+        extra_opts: {type}`list[str]` Additional options to pass onto Sphinx building.
+                    On each provided option, a location expansion is performed.
+                    See {any}`ctx.expand_location`.
         visibility: Bazel visibility
     """
     _score_needs(
@@ -341,6 +342,7 @@ def sphinx_module(
         deps = deps,
         docs_library_deps = docs_library_deps,
         needs = [d + "_needs" for d in deps],
+        extra_opts = extra_opts,
         testonly = testonly,
         visibility = visibility,
     )

bazel/rules/rules_score/src/sphinx_html_merge.py

@@ -178,6 +178,11 @@ 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,12 +110,13 @@ 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) -> List[str]:
+def build_sphinx_arguments(args: argparse.Namespace, extra_args: List[str] = None) -> List[str]:
     """
     Build the argument list for Sphinx.
 
     Args:
         args: Parsed command-line arguments
+        extra_args: Additional arguments to forward to Sphinx (e.g., -D options from extra_opts)
 
     Returns:
         List of arguments to pass to Sphinx
@@ -154,6 +155,10 @@ def build_sphinx_arguments(args: argparse.Namespace) -> List[str]:
 
     base_arguments.extend(["-b", args.builder])
 
+    # Forward extra options (e.g., -D flags) to Sphinx
+    if extra_args:
+        base_arguments.extend(extra_args)
+
     return base_arguments
 
 
@@ -240,7 +245,7 @@ def parse_arguments() -> argparse.Namespace:
         help=f"Port to use for live preview (default: {DEFAULT_PORT}). Use 0 for auto-detection.",
     )
 
-    return parser.parse_args()
+    return parser.parse_known_args()
 
 
 def main() -> int:
@@ -251,14 +256,17 @@ def main() -> int:
         Exit code (0 for success, non-zero for failure)
     """
     try:
-        args = parse_arguments()
+        args, extra_args = parse_arguments()
         validate_arguments(args)
+        logger.info(f"[DEBUG] extra_args from parse_known_args: {extra_args}")
+        logger.info(f"[DEBUG] sys.argv was: {sys.argv}")
         # Create processor instance
         stdout_processor = StdoutProcessor()
         stderr_processor = StderrProcessor()
         # Redirect stdout and stderr
         with redirect_stderr(stderr_processor), redirect_stdout(stdout_processor):
-            sphinx_args = build_sphinx_arguments(args)
+            sphinx_args = build_sphinx_arguments(args, extra_args)
+            logger.info(f"[DEBUG] Final sphinx_args: {sphinx_args}")
             exit_code = run_sphinx_build(sphinx_args, args.builder)
         return exit_code
     except ValueError as e: