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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions