Conversation
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
avengineers/SPLed develop has two commits the useblocks fork lacks: spl-core 8.9 with a refreshed lock (f5ba89e), and the light controller state machine fix (b8beee9). Conflicts, and how they were resolved: - components/light_controller/doc/index.md: upstream nests the blink states in LIGHT_ON, inside a Jinja `{% if config.BLINKING %}` block. This branch turned that block into `{if} var.features.BLINKING` fences, so the fix goes into the BLINKING diagram, without the Jinja markers. - pypeline.yaml: upstream only quoted `python_version: "3.11"`; the fork had already replaced that key with `python_executable: python3`. Kept the fork's. - poetry.lock: upstream's refreshed lock, re-resolved against this branch's pyproject.toml. sphinx-codelinks stays at 1.4.0, the version this branch ran, with typer 0.26.7, because codelinks 1.4.0 caps typer below 0.26.8. - uv.lock, which only the fork keeps: aligned to the same versions. One conflict git could not see: the refreshed lock brings sphinx-needs 8.5.0, which loads needs_from_toml at config-inited priority 10 and resolves the variant data at 11. conf.py selected the variant data file at priority 20, too late, so every build either failed on a missing `build/autoconf.json` or silently read that pointer instead of the cell it was given. conf.py now selects it at priority 10, between the two.
The documentation changes this project needs from spl-core are not in a release yet: optional Jinja raw tags on generated listings, a variant data file per Sphinx build shape, a stable path to the build directory for the generated pages, and KConfig.declared_boolean_symbols(). They live on the feat/configurable-docs-pipeline branch of useblocks/spl-core, five commits on top of spl-core 8.9.0. Pin that commit, so CI and every machine build the same code. In both lock files only spl-core's source changes. Nothing uses the new settings yet; the following commits do.
KConfig omits a promptless boolean from its output when it evaluates to n, so the variant data defaults every declared boolean to false first. Finding them meant reading the kconfiglib instance spl-core keeps privately, behind a fallback for spl-core versions without an accessor. The pinned spl-core has KConfig.declared_boolean_symbols(), so call it and drop the fallback.
…orkarounds
The pinned spl-core can now be told what this project's documentation
needs, so each workaround in conf.py and CMakeLists.txt gives way to one
setting.
Jinja markers. SPL_SOURCE_DOCS_JINJA_RAW_TAGS OFF: clanguru no longer wraps
the generated listings in `{% raw %}`, and conf.py's source-read handler that
blanked the markers again is deleted. conf.py registers no handler at all.
Variant data per build shape. SPL_VARIANT_DATA_FILE_DOCS and _REPORTS name
the cells, and spl-core passes the right one to every Sphinx build as
`-D needs_variant_data_file=`. The fixed-name copies CMake published and
conf.py's fallback that read them are deleted. Nothing in conf.py selects a
cell any more, which is also the only way that works with sphinx-needs 8.5:
it replaces conf.py's values with ubproject.toml's and resolves the variant
data before a config-inited handler at the old priority runs, so the old
selection was silently ignored there. The tests and the VS Code task select a
cell the same way, and it is the same key `ubc check -c` overrides.
Stable report paths. SPL_SPHINX_BINARY_DIR points spl-core at `generated`,
the link tools/variant_data.py maintains, so every generated page is named
`generated/...`. The report sections name their pages directly instead of
globbing `/build/**`, spl-core writes each coverage report next to its page,
and SplBuild finds the report artifacts there. conf.py prunes `build` from
the walk, so each page has exactly one name, and forwards only spl-core's
`generated/` patterns: the `generated/**` rule in ubproject.toml keeps them
out of a docs build, declaratively, for both readers. On Windows without
Developer Mode, `generated` becomes a junction instead of a marker directory,
because the report pages are now read through it.
The tests follow: they drive the fake report tree through `generated`,
check the settings CMake hands spl-core, and assert conf.py registers no
source-read handler. The strip's line-number test is gone with the strip.
VARIANTS.md walks a newcomer through the declarative variant handling in 18 use cases: switching the variant ubCode shows, previewing any variant with Sphinx or ubc, comparing two variants, trying a change on a copy of a variant data file, and writing, extending and checking variant- dependent documentation. Every command in it was run against this branch. It sits at the root, outside both readers' document sets, so neither Sphinx nor ubCode indexes it. README.md and AGENTS.md link to it.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #2. This branch pins spl-core to a commit of the useblocks fork that adds the settings #2 was missing, and deletes the workarounds #2 needed without them. It also brings in the two upstream commits the fork lacked, so the branch is 0 commits behind avengineers/SPLed
develop.spl-core changes: useblocks/spl-core#4, five commits on top of spl-core 8.9.0.
What changes
SPL_SOURCE_DOCS_JINJA_RAW_TAGS OFF{% raw %}markers. conf.py'ssource-readstrip is gone, and conf.py registers no handler at all.SPL_VARIANT_DATA_FILE_DOCS/_REPORTS-D needs_variant_data_file=. The fixed-namebuild/variant-data-*.jsoncopies and conf.py's variant selection are gone. Tests and the VS Code task select a cell the same way, with the keyubc check -coverrides.SPL_SPHINX_BINARY_DIR=generatedgenerated/components/<c>/reports/..., so the report sections name them directly and no document globs/build/**. Coverage links follow the pages. conf.py prunesbuildfrom the walk and forwards only spl-core'sgenerated/patterns, and thegenerated/**rule keeps them out of docs builds.KConfig.declared_boolean_symbols()tools/variant_data.pyis gone.On Windows without Developer Mode,
generatednow becomes a junction rather than a marker directory, because the report pages are read through it.The upstream merge
The first commit merges avengineers/SPLed
develop: spl-core 8.9 with a refreshed lock, and the light controller state machine fix. The commit message lists how each conflict was resolved.One conflict only showed at run time. The refreshed lock brings sphinx-needs 8.5.0, which resolves the variant data right after loading
needs_from_toml. #2's conf.py selected the file later, atconfig-initedpriority 20. With 8.5.0 every build therefore either failed on a missingbuild/autoconf.jsonor quietly read that pointer instead of its cell, which leaves a reports build without reports. The merge fixes that at priority 10. The last commit replaces the mechanism with the command-line override, which sphinx-needs keeps ahead of the TOML.Verification
test_documentation.py,test_ubproject_config.pyandtest_variant_data.py: 94 passed, 1 skipped (the ubc requirement check, which only runs in CI).pytest -m "docs and gate_develop_pr"withCI_REQUIRE_UBC=1and ubc 0.35.0: 31 passed, on this branch and on the merge and accessor commits below it.reportsanddocstargets. Every report page sits undergenerated/, both kinds of coverage link resolve, the verification sections render in the reports build and not in the docs build, andSplBuildfinds all 16 report artifacts. A docs build whosegeneratedlink was re-pointed at another directory stops with spl-core's message.generated. https://github.com/useblocks/SPLed/actions/runs/35985268428test_a_refused_symlink_falls_back_to_a_junction.Unchanged here
generated/reports/*_index.mdare not in any toctree. That gives five warnings on Disco, as before underbuild/.