Feat/improve variant handling

[LuSilber]

Improve variant handling according to https://claude.ai/artifact/7jXCBz4nJUEzdsJLmvUDds?sk=ZcW4woUQGf_vz29cROHdgA. First attempt to remove Jinja from this repository.

[LuSilber]

note: spe-core changes are still open

[ubmarco]

Thanks Lucas, this is really good work. I read it against the concept note, and it does not just implement it, it improves on it in several places:

• tools/variant_data.py writes the complete matrix, with every declared boolean present and the component list read from parts.cmake, so the product structure is stated once. The parts.cmake parser failing loudly on grammar it does not know is exactly the right failure mode.
• ubproject.toml is now genuinely the one configuration both readers read, and test_ubproject_config.py guarding the vendored spl-core base against drift is a nice touch.
• Gating on membership instead of feature or variant name, the static 150% components page, and no source-read hook anywhere: that is the model we want, and the AGENTS.md section explains it well enough that the next person will keep it that way.
• The compiler-free documentation gate is the fastest signal in the workflow and covers every variant. CI is green on all five jobs.

What follows are improvements, ordered by how much I think they matter. Only the first one I would sort out before merging, and even that one may simply be "land the spl-core change first". No earlier review comments to check; your note that the spl-core changes are still open is the context for 1 and 5. The correctness pass is manual, I did not run the review engine.

1. [High] With the Jinja hook gone, the {% raw %} markers in the generated source listings reach the reader (correctness)
The pinned spl-core 8.6.0, and every released spl-core through 9.0.0, still passes --jinja-raw-tags to clanguru, so each __source_docs/*.rst wraps its code in {% raw %} / {% endraw %} lines. The reports target includes build/**/__source_docs/** through conf.py, and the only consumer of those markers was the hook this PR deletes, so in a reports build they now render as literal paragraphs on every listing page. The reports gate only checks the exit code, so nothing catches it. Two ways out: land the spl-core change that drops the flag and bump the pin before merging, or add a handler scoped to docnames under __source_docs that strips exactly those two marker lines (a tag strip, not a template render) with a test that greps the built HTML. Deleting the hook was still the right call.

SPLed/conf.py

Lines 167 to 175 in 6c4e9b4

	def setup(app):
	"""Apply the per-build-shape variant data file, after the TOML is read."""
	if not _variant_data_file:
	return
	def _select_variant_data(app, config):
	config.needs_variant_data_file = _variant_data_file
	app.connect("config-inited", _select_variant_data, priority=20)

2. [Medium] The docs target reads the generated report pages and reports them as orphans (correctness)
spl-core's docs config.json lists every component's reports/** among its include patterns, and it writes unit_test_spec.rst, unit_test_results.rst and coverage.rst at configure time, so they exist. conf.py now forwards every build/ pattern unfiltered; with the report fences false in a docs build, the pages are read and referenced nowhere, which is toc.not_included three times per component. The sphinx-mounts branch filtered these, and the rule meant to replace that filter names generated/**, which Sphinx never discovers, so it is inert for now. Restoring the filter, or gating the build/**/reports/** paths, fixes it. The compiler-free gate cannot see this because a bare build has no spl-core config, so a CMake docs build is the way to confirm.

SPLed/conf.py

Lines 160 to 164 in 6c4e9b4

	include_patterns.extend(
	pattern
	for pattern in _build_config.get("include_patterns", [])
	if pattern.startswith("build/")
	)

3. [Medium] The Windows fallback copies the whole CMake binary directory on every configure (durability)
When the symlink is refused, copytree copies ${CMAKE_BINARY_DIR} (objects, binaries, CMakeFiles) into generated/ at configure time, before the reports target has produced anything, and dirs_exist_ok never removes what a previous configure left. Since generated/ has no consumer yet (see 5), the cheapest fix is to write nothing there until it does, or a marker file instead of a copy.

SPLed/tools/variant_data.py

Lines 274 to 280 in 6c4e9b4

	try:
	current.symlink_to(build_dir.resolve(), target_is_directory=True)
	except OSError:
	# Windows without Developer Mode refuses a symlink. A copy keeps the
	# path stable at the cost of duplicating the tree; the reports target
	# rewrites its output wholesale anyway.
	shutil.copytree(build_dir, current, dirs_exist_ok=True)

4. [Medium] The two-reader guarantee is not yet enforced in CI (durability)
test_ubc_excludes_exactly_what_sphinx_excludes is the property the whole design exists for, and it is a great test. It skips when ubc is absent, which it is on every runner, so today it only holds on a developer machine. ubc ships as a GitHub Action: adding it to the documentation job, passing the license through UBCODE_LICENSE_KEY / UBCODE_LICENSE_USER from repository secrets and pointing UBC at the installed binary would make the skip unnecessary. Turning the skip into a failure when CI is set then guarantees a missing ubc can never make the parity tests pass by omission. As a bonus, this repo becomes a standing parity check of Sphinx-Needs against every ubCode release.

SPLed/test/test_documentation.py

Lines 191 to 192 in 6c4e9b4

	UBC = _find_ubc()
	needs_ubc = pytest.mark.skipif(UBC is None, reason="ubc not found; set UBC or put it on PATH")

5. [Low] The forward-looking generated/ config is inert in both readers today, and will double-discover when it goes live (architecture)
[parse.parsers.rst] include = ["generated/**/*.rst"], the generated/** rule and the generated/... entries in every component rule currently do nothing, exactly as your comments say: Sphinx's include set never names generated/, and ubCode does not descend symlinks. When the spl-core change makes the path real, Sphinx will discover the same pages under build/<V>/... through spl-core's patterns as well, so the build/ forwarding in conf.py has to go in the same change or every report page exists twice. Either drop the generated lines until then, or record that coupling next to the rule so it is not forgotten.

SPLed/ubproject.toml

Lines 252 to 254 in 6c4e9b4

	[[source.variant_sources]]
	if = 'var.build_config.target == "reports"'
	files = ["generated/**"]

6. [Low] Sphinx walks the whole build directory a second time through the generated symlink (performance)
get_matching_files walks with followlinks=True, and neither exclude_patterns nor the include set stops the descent. Adding generated to exclude_patterns in conf.py:25-32 until it carries documents avoids the double walk.

7. [Low] The variant-selection task can point ubCode at the reports cell (correctness)
CMake always writes the docs cell as the pointer, so the IDE sees a clean false on every report fence. The task passes ${input:docsTarget} to --current; with reports chosen, every fence opens a glob toctree into build/**, which ubCode excludes, and each component reports an unmatched glob. Keeping the target choice for the Sphinx build task and dropping it from --current keeps the IDE quiet.

SPLed/.vscode/tasks.json

Lines 31 to 34 in 6c4e9b4

	"label": "Select documentation variant",
	"detail": "Point the docs and ubCode at one variant -- no CMake, no compiler",
	"type": "shell",
	"command": "${command:python.interpreterPath} tools/variant_data.py --variant ${input:variant} --kit ${input:buildKit} --target ${input:docsTarget} --current",

8. [Low] AGENTS.md says documents name generated/ instead of globbing /build/**; all seven still glob (docs)
The deferral conf.py explains (gcovr writes next to the build-relative page path) is the right call; the text could describe the deferral rather than the end state, e.g. components/auto_off/doc/index.md:131-135.

SPLed/AGENTS.md

Lines 287 to 290 in 6c4e9b4

	`generated/` is the configured variant's build directory. Documents name it
	directly instead of globbing `/build/**`; a glob matched every variant and build
	type on disk and only ever resolved to one page because `conf.py` narrowed the
	source set behind the scenes.

Backwards compatibility, worth a line in the PR description: the Python floor moves from 3.11 to 3.12, so an existing venv needs build.sh --clean --install; ubproject.toml no longer extends spl-core's base config, so spl-core needs-model changes now require re-vendoring (guarded by test_ubproject_config.py); index.md loses the timestamp line by design.

Direction, not for this PR. Two things this PR makes visible, both waiting on the same spl-core changes:

• Documents should never name CMake's build/ tree. Renaming that directory is not worth it (build scripts, VS Code settings, CI artifacts all know it); making generated/ the only docs-facing path, as this PR prepares, and deleting every /build/** glob once spl-core writes the coverage tree relative to it, is.
• The Sphinx source root should be a docs/ folder, not the repository, so neither reader has to filter the whole repo. The co-located components/<c>/doc trees are what [[source.mounts]] is for: mounted from ../components/<c>/doc at components/<c>, gated on membership exactly like the rules are now, and the generated reports mounted from ../generated. The parser-mode include lists, their sync test, and the sources_from_toml = None branch all disappear. It needs a Sphinx source directory knob in spl-core (_sphinx_source_dir is hard-coded to PROJECT_SOURCE_DIR today), which makes it the natural second step after the pending spl-core release.

Again, really nice work. Happy to pair on 1 and 2 if useful.