Skip to content

feat(docs): use spl-core's documentation settings and drop the workarounds - #3

Draft
ubmarco wants to merge 7 commits into
feat/improve-variant-handlingfrom
feat/adopt-spl-core-docs-pipeline
Draft

ubmarco wants to merge 7 commits into
feat/improve-variant-handlingfrom
feat/adopt-spl-core-docs-pipeline

Conversation

@ubmarco

@ubmarco ubmarco commented Sep 24, 2026

Copy link
Copy Markdown
Member

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-core setting What SPLed gains or deletes
SPL_SOURCE_DOCS_JINJA_RAW_TAGS OFF Generated listings carry no {% raw %} markers. conf.py's source-read strip is gone, and conf.py registers no handler at all.
SPL_VARIANT_DATA_FILE_DOCS / _REPORTS spl-core passes each build its cell as -D needs_variant_data_file=. The fixed-name build/variant-data-*.json copies and conf.py's variant selection are gone. Tests and the VS Code task select a cell the same way, with the key ubc check -c overrides.
SPL_SPHINX_BINARY_DIR = generated The report pages have stable names, generated/components/<c>/reports/..., so the report sections name them directly and no document globs /build/**. Coverage links follow the pages. conf.py prunes build from the walk and forwards only spl-core's generated/ patterns, and the generated/** rule keeps them out of docs builds.
KConfig.declared_boolean_symbols() The kconfiglib fallback in tools/variant_data.py is gone.

On Windows without Developer Mode, generated now 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, at config-inited priority 20. With 8.5.0 every build therefore either failed on a missing build/autoconf.json or 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

  • Documentation tests, test_documentation.py, test_ubproject_config.py and test_variant_data.py: 94 passed, 1 skipped (the ubc requirement check, which only runs in CI).
  • CI documentation gate, pytest -m "docs and gate_develop_pr" with CI_REQUIRE_UBC=1 and ubc 0.35.0: 31 passed, on this branch and on the merge and accessor commits below it.
  • End to end on Linux, gcc 16, CMake 4.4: Disco test kit reports and docs targets. Every report page sits under generated/, both kinds of coverage link resolve, the verification sections render in the reports build and not in the docs build, and SplBuild finds all 16 report artifacts. A docs build whose generated link was re-pointed at another directory stops with spl-core's message.
  • Full CI, started manually on this branch: green on Windows, Linux, the devcontainer and the documentation gate. On Windows, 92 passed and 12 skipped, including every variant's reports test through generated. https://github.com/useblocks/SPLed/actions/runs/35985268428
  • The Windows log does not show whether the runner got a symlink or the junction fallback. The fallback itself is covered by test_a_refused_symlink_falls_back_to_a_junction.

Unchanged here

  • spl-core's per-component wrapper pages generated/reports/*_index.md are not in any toctree. That gives five warnings on Disco, as before under build/.
  • The integration suite's source listings define the same implementation needs as the components' own listings, which gives five duplicate-ID warnings on Disco, as before.

cuinixam and others added 7 commits August 17, 2026 08:59
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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants