Skip to content

Ops docs: fix unresolved partial includes, drop void backend, render LaTeX #513

@michalharakal

Description

@michalharakal

Follow-up to #511. The first pass of the KSP TensorOps surface scan shipped with several rendering issues on the published site at
skainet-developers.github.io/SKaiNET/skainet/reference/operators/generated/tensorops.html.

Problems

  1. Unresolved partial$ includes on ~50 operators. The generator emits include::partial\$ops/tensorops/<fn>.adoc[...optional] for every function, but Antora does not honour the optional attribute for resource refs — missing partials render as Unresolved include directive errors. Only matmul has a partial today, so every other op is broken.
  2. Stub VoidTensorOps page. VoidTensorOps is @Backend(id="void"), a shape-only sentinel with no runtime. The annotation-grouping path produces a standalone voidtensorops.adoc that lists only the 2 @InProgress-annotated methods, duplicating coverage info that already lives in the TensorOps surface scan's backend matrix.
  3. void surfaced as a real backend. Backend badges/tables exposed void as if it were a deployable backend.
  4. LaTeX not rendered. stem:[…] and [stem] blocks in partials/ops/tensorops/matmul.adoc are emitted as literal \$…\$ passthrough because the UI bundle has no MathJax and the playbook does not set stem: latexmath.

Fix plan

  • Generator: only emit include::partial\$… directives when the partial file exists on disk (walk from outputDir up to pages/ and check sibling partials/). Stop emitting per-function backend chrome — platform support per op is not an issue yet.
  • KSP: drop annotation-derived symbols whose enclosing class is @Backend-tagged (already covered by the TensorOps surface scan). Add internal: Boolean = false to @Backend, tag VoidTensorOps as internal = true, and filter internal backends out of the surface scan.
  • Docs: set asciidoc.attributes.stem: latexmath in antora-playbook.yml and inject MathJax v3 via a supplemental UI override of partials/footer-scripts.hbs.

Verification

Local Antora build (docs/.docker image, playbook unchanged except for the additions above):

  • tensorops.html contains zero Unresolved include errors; every op shows signature → parameters → return type; only matmul additionally shows Definition / Intuition / Examples / References from its partial.
  • No voidtensorops.html page.
  • MathJax loads on every page; \(…\) and \[…\] delimiters in the matmul section render as real math.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions