[rules score] several dependable element fixes

.bazelrc

@@ -42,3 +42,6 @@ coverage:coverage --@rules_rust//rust/settings:extra_rustc_flag=-Ccodegen-units=
 
 # Import AI checker custom configuration
 try-import %workspace%/.bazelrc.ai_checker
+
+# Import Bazel Userrc
+try-import %workspace%/user.bazelrc

.gitignore

@@ -8,6 +8,10 @@ external
 .vscode/
 .clwb/
 
+# Per-developer Bazel overrides (e.g. a local disk cache path), imported via
+# `try-import %workspace%/user.bazelrc` in .bazelrc.
+user.bazelrc
+
 __pycache__
 .ruff_cache/
 coverage-html/

bazel/rules/rules_score/BUILD

@@ -114,6 +114,13 @@ py_binary(
 )
 
 # HTML merge tool
+py_library(
+    name = "sphinx_html_merge_lib",
+    srcs = ["src/sphinx_html_merge.py"],
+    imports = ["src"],
+    visibility = ["//visibility:public"],
+)
+
 py_binary(
     name = "sphinx_html_merge",
     srcs = ["src/sphinx_html_merge.py"],
@@ -127,6 +134,7 @@ py_library(
     imports = ["src"],
     visibility = ["//visibility:public"],
     deps = [
+        ":bazel_sphinx_needs",
         requirement("sphinx"),
     ],
 )
@@ -141,6 +149,20 @@ py_library(
     ],
 )
 
+# Shared conf.py building blocks (hermetic plantuml/graphviz/FTA resolution,
+# metamodel needs schema loading). Used by the default conf.template.py and
+# available to any consumer who supplies their own conf_template.
+py_library(
+    name = "sphinx_conf_helpers",
+    srcs = ["src/sphinx_conf_helpers.py"],
+    imports = ["src"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":bazel_sphinx_needs",
+        requirement("sphinx"),
+    ],
+)
+
 # ---------------------------------------------------------------------------
 # Tool reference pages: each README.md is renamed to <name>.md via
 # renamed_srcs on sphinx_module. No sphinx_docs_library needed for renames —
@@ -208,19 +230,15 @@ sphinx_module(
     visibility = ["//visibility:public"],
 )
 
-# HTML merge tool
-
-py_binary(
-    name = "raw_build",
-    srcs = ["src/sphinx_wrapper.py"],
-    env = {
-        "SOURCE_DIRECTORY": "",
-        "DATA": "",
-        "ACTION": "check",
-    },
-    main = "src/sphinx_wrapper.py",
+# Dependency set for the default Sphinx build binary. Extracted into its own
+# py_library so score_sphinx_toolchain() (sphinx_toolchain.bzl) can pull it in
+# as a base for consumers who only want to add extensions, without
+# copy-pasting this list.
+py_library(
+    name = "sphinx_base_deps",
     visibility = ["//visibility:public"],
     deps = [
+        ":sphinx_conf_helpers",
         ":sphinx_module_ext",
         "@lobster//sphinx_lobster:sphinx_lobster_builder",
         "@score_tooling//plantuml/sphinx/clickable_plantuml",
@@ -236,6 +254,19 @@ py_binary(
     ],
 )
 
+py_binary(
+    name = "raw_build",
+    srcs = ["src/sphinx_wrapper.py"],
+    env = {
+        "SOURCE_DIRECTORY": "",
+        "DATA": "",
+        "ACTION": "check",
+    },
+    main = "src/sphinx_wrapper.py",
+    visibility = ["//visibility:public"],
+    deps = [":sphinx_base_deps"],
+)
+
 sphinx_toolchain(
     name = "default_toolchain",
     sphinx = ":raw_build",

bazel/rules/rules_score/docs/_assets/tooling_chain.puml

@@ -47,7 +47,7 @@ rectangle "**puml_cli** (FTA mode)\ninline metamodel + extract\n(.puml -> inline
 rectangle "**fmea_assembler**\nTRLCRST page build\n(.trlc + chains -> fmea.rst)" <<own>> as asm
 rectangle "**Lobster**\nlobster-trlc / -report /\n-ci-report / gtest_report" <<tool>> as lob
 rectangle "**Architecture Verifier**\nvalidation_cli\n(arch.json + .fbs.bin)" <<tool>> as verifier
-rectangle "**Sphinx**\nscore_build + html_merge\n(.rst -> needs.json + HTML)" <<tool>> as docs
+rectangle "**Sphinx**\ntoolchain-resolved build binary + private\nhtml_merge tool\n(.rst -> needs.json + HTML)" <<tool>> as docs
 
 ' ── Tool-qualification branch (traces tool requirements to source) ────────────
 rectangle "rules_score_impl\n(tool-qualification target)" <<rule>> as impl

bazel/rules/rules_score/docs/integration_guide.rst

@@ -31,25 +31,103 @@ produce the final outputs.
 Toolchain Setup
 ---------------
 
-The ``sphinx_toolchain`` rule configures the Sphinx build environment with
-custom extensions. External modules must define and register their own toolchain
-to use ``rules_score``.
+``rules_score`` ships a default Sphinx toolchain, registered by ``score_tooling``'s
+own ``MODULE.bazel``. **You need nothing to get a working Sphinx build** — plain
+sphinx-needs, TRLC and PlantUML documentation builds out of the box for any
+module that depends on ``score_tooling``, with no toolchain setup at all.
+
+Registering your own toolchain is only needed when you want **additional**
+Sphinx extensions (e.g. Breathe for Doxygen, a custom theme) that the default
+doesn't carry. Because Bazel resolves toolchains from the root module first,
+a toolchain registered by your own ``MODULE.bazel`` always wins over
+``score_tooling``'s default — no special opt-out required.
+
+Adding extensions
+~~~~~~~~~~~~~~~~~
+
+Use the ``score_sphinx_toolchain`` macro to extend the default dependency set
+instead of reproducing it:
 
 **MODULE.bazel:**
 
 .. code-block:: python
 
-   # Add rules_score dependency
    bazel_dep(name = "score_tooling", version = "1.3.2")
 
-   # Add dependencies for custom Sphinx extensions (if needed)
-   bazel_dep(name = "score_docs_as_code", version = "3.0.1")
+   # Dependency providing your custom Sphinx extension
+   bazel_dep(name = "score_docs_as_code", version = "3.0.1", dev_dependency = True)
 
-   # Register your custom toolchain
    register_toolchains("//:my_toolchain")
 
 **BUILD:**
 
+.. code-block:: python
+
+   load("@score_tooling//bazel/rules/rules_score:sphinx_toolchain.bzl", "score_sphinx_toolchain")
+
+   score_sphinx_toolchain(
+       name = "my_toolchain",
+       extra_deps = [
+           "@score_docs_as_code//src/extensions/score_sphinx_bundle",
+       ],
+   )
+
+This emits ``my_toolchain_binary`` (the Sphinx build binary: the shared
+defaults plus ``extra_deps``), ``my_toolchain_info`` (the ``sphinx_toolchain``
+target) and ``my_toolchain`` (the ``toolchain()`` itself) — register the last
+one.
+
+Diagnosing which toolchain won
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+   bazel cquery --toolchain_resolution_debug='.*rules_score.*' //:my_target
+
+Look for the ``Selected ... toolchain`` line under
+``@score_tooling//bazel/rules/rules_score:toolchain_type``.
+
+Replacing the dependency set entirely
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your extensions conflict with the shared defaults — e.g. a different pip
+hub pinning an incompatible version of a shared package — pass ``deps``
+instead of ``extra_deps`` to bypass ``sphinx_base_deps`` entirely and supply
+the full list yourself:
+
+.. code-block:: python
+
+   score_sphinx_toolchain(
+       name = "my_toolchain",
+       conf_template = "//:my_conf.template.py",
+       deps = [
+           "@score_tooling//bazel/rules/rules_score:sphinx_module_ext",
+           "@my_pip_hub//sphinx:pkg",
+           "@my_pip_hub//my_custom_extension:pkg",
+           # ... full list; sphinx_base_deps is not included in this mode
+       ],
+   )
+
+``extra_deps`` and ``deps`` are mutually exclusive — passing both fails at
+load time.
+
+**score_sphinx_toolchain parameters:**
+
+- ``name`` — name of the emitted ``toolchain()`` target (mandatory)
+- ``extra_deps`` — extend mode: extra deps added on top of the shared default set (optional; default: ``[]``)
+- ``deps`` — replace mode: exact dep list, bypassing the shared defaults (optional; default: not set)
+- ``extra_data`` — extra data files/targets for the Sphinx build binary (optional; default: ``[]``)
+- ``conf_template`` — Label to ``conf.py`` template (optional; default: ``@score_tooling//bazel/rules/rules_score:templates/conf.template.py``)
+- ``package_collisions`` — forwarded to the generated ``py_binary`` (optional; default: ``"warning"``)
+- any other keyword argument (e.g. ``visibility``, ``exec_compatible_with``, ``target_compatible_with``) is forwarded to the ``toolchain()`` target
+
+Assembling a toolchain by hand
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cases the macro doesn't fit, use the underlying ``sphinx_toolchain`` rule
+directly — it only bundles a Sphinx binary and a ``conf.py`` template into the
+provider the rules consume; you own the ``py_binary`` and ``toolchain()``:
+
 .. code-block:: python
 
    load("@aspect_rules_py//py:defs.bzl", "py_binary")
@@ -61,10 +139,8 @@ to use ``rules_score``.
        main = "@score_tooling//bazel/rules/rules_score:src/sphinx_wrapper.py",
        visibility = ["//visibility:public"],
        deps = [
-           "@score_tooling//bazel/rules/rules_score:sphinx_module_ext",
-           "@score_docs_as_code//src:plantuml_for_python",
+           "@score_tooling//bazel/rules/rules_score:sphinx_base_deps",
            "@score_docs_as_code//src/extensions/score_sphinx_bundle",
-           # Add your custom Sphinx extensions here
        ],
    )
 
@@ -75,24 +151,19 @@ to use ``rules_score``.
 
    toolchain(
        name = "my_toolchain",
-       exec_compatible_with = [
-           "@platforms//os:linux",
-           "@platforms//cpu:x86_64",
-       ],
-       target_compatible_with = [
-           "@platforms//os:linux",
-           "@platforms//cpu:x86_64",
-       ],
        toolchain = ":score_sphinx_toolchain",
        toolchain_type = "@score_tooling//bazel/rules/rules_score:toolchain_type",
        visibility = ["//visibility:public"],
    )
 
 **sphinx_toolchain parameters:**
 
-- ``sphinx`` — Label to the Sphinx build binary (mandatory)
+- ``sphinx`` — Label to the Sphinx build binary (optional; default: ``@score_tooling//bazel/rules/rules_score:raw_build``)
 - ``conf_template`` — Label to ``conf.py`` template (optional; default: ``@score_tooling//bazel/rules/rules_score:templates/conf.template.py``)
-- ``html_merge_tool`` — Label to HTML merge tool (optional; default: ``@score_tooling//bazel/rules/rules_score:sphinx_html_merge``)
+
+The HTML-merge tool used to combine dependency HTML trees is a fixed,
+private implementation detail of ``sphinx_module`` — it is not part of
+``SphinxInfo`` and cannot be overridden.
 
 
 Cross-module dependencies

bazel/rules/rules_score/docs/rule_reference.rst

@@ -59,10 +59,6 @@ cross-module dependencies and automatic HTML merging.
      - label list
      - no
      - Other ``sphinx_module`` or ``dependable_element`` targets for cross-referencing and HTML merging (default ``[]``)
-   * - ``sphinx``
-     - label
-     - no
-     - Override the Sphinx binary (default: toolchain-provided binary)
    * - ``testonly``
      - bool
      - no

bazel/rules/rules_score/docs/tooling_architecture.rst

@@ -140,10 +140,11 @@ are rendered under :doc:`tool_reference/index`.
        against the *expected* architecture (static/dynamic ``.fbs.bin`` from
        ``architectural_design``). Fails the build on a mismatch.
    * - **Sphinx (Docs)**
-     - ``score_build`` (``src/sphinx_wrapper.py``),
-       ``html_merge_tool`` (``src/sphinx_html_merge.py``),
-       ``sphinx_module_ext``,
-       ``trlc`` Sphinx extension (``@trlc``)
+     - Sphinx build binary (``src/sphinx_wrapper.py``, resolved via the
+       registered ``sphinx_toolchain``), HTML merge tool
+       (``src/sphinx_html_merge.py``, a private rule detail — not toolchain-
+       configurable), ``sphinx_module_ext``, ``trlc`` Sphinx extension
+       (``@trlc``)
      - ``sphinx_module``, ``dependable_element``
      - Two-phase documentation build: **phase 1** (``<name>_needs`` target)
        runs Sphinx with ``--builder needs`` to emit ``needs.json`` containing

bazel/rules/rules_score/examples/some_other_library/bazel/toolchains/BUILD

@@ -11,10 +11,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
-load(
-    "@score_tooling//bazel/rules/rules_score:sphinx_toolchain.bzl",
-    "sphinx_toolchain",
-)
 load(
     "@score_tooling//cpp/libclang:libclang_toolchain.bzl",
     "libclang_toolchain",

bazel/rules/rules_score/private/dependable_element.bzl

@@ -1527,7 +1527,6 @@ def dependable_element(
         deps = [],
         aou_forwarding = None,
         maturity = "release",
-        sphinx = Label("//bazel/rules/rules_score:score_build"),
         testonly = True,
         docs_prefix = "docs/sphinx/",
         **kwargs):
@@ -1568,7 +1567,6 @@ def dependable_element(
         aou_forwarding: Optional label to a YAML file listing received AoU IDs
             to further-forward to this element's own dependees. Only needed for
             chain-forwarding received AoUs that this element cannot handle.
-        sphinx: Label to sphinx build binary. Default: //bazel/rules/rules_score:score_build
         testonly: If True, only testonly targets can depend on this target.
         docs_prefix: Prefix under which the generated `<name>_rst` sphinx_docs_library
             exposes its RST sources, so that an external Sphinx build can embed it via
@@ -1619,7 +1617,6 @@ def dependable_element(
         srcs = [":" + name + "_index"],
         index = ":" + name + "_index",
         deps = [d + _DOC_TARGET_SUFFIX for d in deps],
-        sphinx = sphinx,
         testonly = testonly,
         **kwargs
     )