Fact-check and correct migrated Antora docs (#499)#500
Merged
michalharakal merged 3 commits intodevelopfrom Apr 13, 2026
Merged
Fact-check and correct migrated Antora docs (#499)#500michalharakal merged 3 commits intodevelopfrom
michalharakal merged 3 commits intodevelopfrom
Conversation
Fact-check pass over the migrated Antora docs surfaced eight stale version references and two wrong Maven group coordinates — all inherited from the pre-Antora markdown sources that hadn't been touched in multiple release cycles. ## Version bumps (0.13.0 / 0.5.0 → 0.19.0) The 0.13.0 number dates back at least five releases (develop is currently at 0.18.0 with 0.19.0 about to ship). The 0.5.0 number in io-readers.adoc was even older. Bumped to 0.19.0 to match the upcoming release tag — readers on 0.18.0 are unaffected because every change between 0.13.0 and 0.19.0 is backwards- compatible at the Maven coordinate level (new modules added, nothing renamed). - `how-to/java-cli-app.adoc` — skainet.version property + BOM coordinate in the Gradle snippet - `how-to/java-llm-inference.adoc` — <version> in the Maven snippet - `how-to/java-model-training.adoc` — <version> in the Maven snippet - `how-to/io-readers.adoc` — the two 0.5.0 module coordinates - `tutorials/java-getting-started.adoc` — skainet.version property + BOM coordinate ## Maven group fix (sk.ainet.core → sk.ainet) `io-readers.adoc` lines 23 and 33 wrote the GGUF and ONNX IO module coordinates as `sk.ainet.core:skainet-io-gguf:0.5.0` and `sk.ainet.core:skainet-io-onnx:0.5.0`. The actual Maven group for every published module in this repo is `sk.ainet` (root `build.gradle.kts` line 17, `skainet-bom/build.gradle.kts` line 6). Nothing named `sk.ainet.core` was ever published, so anyone copy-pasting the snippet before this fix would hit unresolvable dependencies. Fixed to `sk.ainet:skainet-io-gguf:0.19.0` and `sk.ainet:skainet-io-onnx:0.19.0` respectively. Verified with a local Antora build — zero warnings, zero errors. First of four commits in the docs fact-check pass. See #499. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The fact-check pass found three pages describing APIs that no
longer live in this repo at all. Per the 2026-04-13 repo split,
LLM runtimes (KLlama, KBert, chat, tools, agent loop, etc.) moved
to the sibling `SKaiNET-transformers` repository. Mainline kept
the engine layer only.
These three pages were survivors from before the split and
collectively held 49 references to packages and Maven coordinates
that don't exist in mainline:
- `sk.ainet:skainet-kllama-jvm` (module)
- `sk.ainet.apps.kllama.java.{KLlamaJava, KLlamaSession,
GenerationConfig}`
- `sk.ainet.apps.bert.java.{KBertJava, KBertSession}`
- `sk.ainet.apps.kllama.chat.java.{JavaAgentLoop, JavaTool,
ToolDefinition}`
Anyone copy-pasting a snippet from these pages into a
mainline-0.19.0 project would hit unresolvable imports and
unresolvable Maven coordinates.
## Changes
1. `tutorials/kllama-getting-started.adoc` — replaced body with
a short CAUTION admonition + redirect to the
SKaiNET-transformers repo and docs site. Notes what DID stay
in mainline (tokenizers via `TokenizerFactory`, model loaders
via `io-readers.adoc`, the Java entry point for tensor ops).
2. `how-to/java-cli-app.adoc` — same treatment. The page
explicitly documented a KLlama CLI; the replacement links
both out to transformers AND inward to `java-getting-started`
and `java-model-training` for non-LLM Java flows that remain
relevant.
3. `how-to/java-llm-inference.adoc` — same treatment, with a
slightly longer "what stayed in mainline" section listing the
concrete tokenizer + TensorEncoding + loader surfaces a Java
LLM integrator can still use locally without bringing in
transformers.
4. `docs/modules/ROOT/nav.adoc` — remove the three nav entries.
Pages still exist (reachable by typed URL, useful if someone
lands on them via a stale search result) but they're no
longer presented as part of the Tutorials / How-to story.
Note on page titles: the stub pages intentionally keep their
original filenames so inbound links (external blogs, old docs
snapshots, Google cache) still land on a useful redirect
instead of 404'ing. Deleting the files outright is reversible
but hostile to readers who arrive via external links.
Local Antora build: zero warnings, zero errors.
Second of four commits in the docs fact-check pass. See #499.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two small fact-check fixes bundled together.
## 1. Pandoc link artifact in jvm-cpu.adoc
`explanation/perf/jvm-cpu.adoc` line 28 still had a markdown-style
link that pandoc never rewrote:
link:java-25-cpu-backend.md[Java 25 CPU Backend]
Two problems:
- wrong extension (`.md` — that file is `.adoc` after the
migration)
- wrong Antora syntax — `link:` is for external URLs, inside a
module you use `xref:` and reference the target as a
module-relative path from `pages/`
Fixed to:
xref:explanation/perf/java-25-cpu-backend.adoc[Java 25 CPU Backend notes]
Antora resolves the xref cleanly now.
## 2. JDK prereq wording normalization
The five pages that mention JDK version requirements had
three different phrasings:
- `tutorials/java-getting-started`, `how-to/java-cli-app`,
`how-to/java-llm-inference`, `how-to/java-model-training`
said "JDK 21 or later" in prose
- `explanation/perf/jvm-cpu` said "JDK 21+ (JDK 22 toolchain
configured by Gradle)"
- `how-to/build` (post-migration) said "Sets up JDK 25"
- CI actually runs JDK 25 via setup-java@v4 in docs.yml,
build.yml, publish.yml, documentation.yml,
schema-validation.yml (and JDK 22 in java-tests.yml which
is the one outlier)
None of these were factually wrong — 21 is the real minimum —
but the version number inconsistency was confusing. Normalized
to "JDK 21 or later (CI builds on JDK 25)" on every prereq line
I could find. The `java-cli-app.adoc` and `java-llm-inference.adoc`
pages were replaced with redirect stubs in the previous commit
so they're excluded from this pass.
Verified with a local Antora build — zero warnings, zero errors.
Third of four commits in the docs fact-check pass. See #499.
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.
Closes #499.
Summary
Fact-check pass over the Antora docs that landed in #494 / #495 + polish from #497. The pandoc markdown → asciidoc conversion preserved every stale claim the source files had accumulated since whenever they were last touched. This PR corrects the four concrete categories the audit found.
Local build stays clean at 0 warnings, 0 errors after every commit.
The three commits
1. `29043130` — stale version refs + wrong Maven group
Eight stale version references bumped from `0.13.0` / `0.5.0` → `0.19.0` (the upcoming release tag — see `CHANGELOG.md` `[Unreleased]`). Covers:
Two wrong-group coordinates fixed in `io-readers.adoc`: `sk.ainet.core:skainet-io-gguf` / `sk.ainet.core:skainet-io-onnx` → `sk.ainet:skainet-io-gguf` / `sk.ainet:skainet-io-onnx`. Nothing under `sk.ainet.core` was ever published — anyone copy-pasting the snippet before this fix would hit unresolvable dependencies.
2. `cfcdb8d2` — replace moved-LLM pages with redirect stubs
Three pages described APIs that moved to `SKaiNET-transformers` on the 2026-04-13 repo split, with 49 references to packages and Maven coordinates that no longer exist in mainline:
Replaced the body of each with a short CAUTION admonition + redirect links to the transformers repo and docs site. The files keep their original paths so inbound links from external blogs / search / old docs snapshots land on a useful redirect instead of a 404. Removed the three nav entries from `docs/modules/ROOT/nav.adoc`.
Pages affected:
Each stub also lists what did stay in mainline and is still useful for LLM workflows (the `TokenizerFactory` for Qwen BPE / SentencePiece, the model loaders in `io-readers.adoc`, the `TensorEncoding` metadata flow for Q4_K / Q8_0 / TernaryPacked).
3. `29585880` — pandoc link artifact + JDK prereq wording
Test plan
Out of scope
🤖 Generated with Claude Code