Ops docs: fix partial includes, LaTeX rendering, version stamp + KDoc params (#513)#514
Merged
michalharakal merged 3 commits intodevelopfrom Apr 15, 2026
Merged
Conversation
) Four follow-ups to the TensorOps surface-scan docs (#511) that landed with rendering bugs on the published site. Generator now only emits `include::partial$ops/<op>/<fn>.adoc[...]` directives for partials that actually exist on disk — Antora does not honour `[optional]` for resource-ref includes, so the prior blanket emission produced "unresolved include" errors on every op except matmul. Partial root is derived from the output dir's Antora `pages/` marker. Per-function backend chrome is removed entirely; platform coverage per op is not a concern yet. `@Backend` annotation gains `internal: Boolean = false`, applied to `VoidTensorOps` which is a shape-only sentinel, not a deployable backend. The KSP surface scan filters internal backends out, and the annotation-grouping path drops symbols whose enclosing class is `@Backend`-tagged (their coverage is already in the surface scan). Result: no standalone `voidtensorops.adoc` stub, no `void` column in badges or matrices. LaTeX in `stem:[…]` and `[stem]` blocks now renders as real math. The playbook sets `asciidoc.attributes.stem: latexmath` so expressions are parsed as LaTeX, and a supplemental UI override at `docs/supplemental-ui/partials/footer-scripts.hbs` injects MathJax v3 from jsDelivr with `\(…\)` / `\[…\]` delimiters matching Asciidoctor's output. Override is local so docs fixes don't require a skainet-docs-ui bundle release. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two related polish items on top of the partial/void/LaTeX fixes. Generated pages now stamp the canonical SKaiNET version — sourced from `VERSION_NAME` in the root `gradle.properties` (the same value published to Maven Central) — instead of the hardcoded "1.0.0" placeholder the KSP processor shipped with. The value is passed via a new `skainet.version` KSP option configured in `skainet-lang-core/build.gradle.kts` and read through `environment.options` on the processor side. Falls back to `"unknown"` when the option is absent so unit-test fixtures that drive the processor directly don't need to thread the value through. Parameter descriptions on the generated operator pages now come from KDoc `@param` directives on the underlying `TensorOps` interface. A new `parseKDocParams` helper walks KSP's raw `docString`, pulls `@param <name> <desc>` blocks (with continuation-line support up to the next `@<tag>` or blank line), and feeds the map into `extractParameters`. Params without KDoc still render as `name: Type` with no description, so ops that haven't been documented yet stay valid. `scaledDotProductAttention` is the reference example — its six params all now carry shape and semantics prose on the generated page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
matmul is the walk-through example for the ops docs pipeline — it already has a prose partial under partials/ops/tensorops/matmul.adoc and gets embedded into the explanation/theory page. Give its interface declaration the matching @param KDoc so the generator's new param-description extraction has something to render on the reference page, mirroring the pattern set by scaledDotProductAttention. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
📖 Documentation Preview The documentation has been built successfully for this PR. Generated Files:
Artifacts:
This comment will be updated automatically when the PR is updated. |
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
1 participant
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.
Fixes #513.
Summary
Four polish follow-ups to #511 (TensorOps surface scan) that shipped with rendering bugs on the published site.
include::partial$ops/<op>/<fn>.adoc[...]when the partial exists on disk. Antora does not honour[optional]for resource-ref includes, so the prior blanket emission produced "unresolved include" errors on every op exceptmatmul. Partials root is derived from the output dir's Antorapages/marker. Per-function backend chrome removed entirely — platform coverage per op is not a concern yet.voidbackend no longer surfaces as a real backend.@Backendannotation gainsinternal: Boolean = false, applied toVoidTensorOps(shape-only sentinel, no runtime). KSP surface scan filters internal backends out, and the annotation-grouping path drops symbols whose enclosing class is@Backend-tagged. No more standalonevoidtensorops.adocstub.asciidoc.attributes.stem: latexmath; supplemental UI override atdocs/supplemental-ui/partials/footer-scripts.hbsinjects MathJax v3 from jsDelivr with\(…\)/\[…\]delimiters matching Asciidoctor's output. Override is local so docs fixes don't require askainet-docs-uibundle release.VERSION_NAMEfrom rootgradle.properties(the same value published to Maven Central) via a newskainet.versionKSP option, replacing the hardcoded"1.0.0"placeholder. Parameter descriptions come from KDoc@paramdirectives on theTensorOpsinterface — a newparseKDocParamshelper walks KSP's rawdocString, pulls@param <name> <desc>blocks with continuation-line support, and feeds them intoextractParameters.matmulandscaledDotProductAttentionare the reference examples.Commits
c4f0ed2b— unresolved partials + void backend + LaTeX rendering3327cba3— real version stamp + KDoc@paramextractionfdb4323e— KDoc@paramonmatmulas a reference exampleTest plan
docs/.dockerimage produces zeroUnresolved includeerrors ontensorops.htmlvoidtensorops.htmlin the built site\(…\)/\[…\]delimiters in the matmul section render as real mathGenerated from version ``0.18.0``` (matchesVERSION_NAME`)matmulandscaledDotProductAttentionparameter bullets carry KDoc prose🤖 Generated with Claude Code