Skip to content

docs: ndarray/nalgebra onboarding, llms.txt conventions, and zero-copy interop - #1655

Merged
shinaoka merged 1 commit into
mainfrom
codex/issue-1641-onboarding
Aug 10, 2026
Merged

docs: ndarray/nalgebra onboarding, llms.txt conventions, and zero-copy interop#1655
shinaoka merged 1 commit into
mainfrom
codex/issue-1641-onboarding

Conversation

@shinaoka

Copy link
Copy Markdown
Member

Fixes #1641

Rust-native onboarding surface: ndarray/nalgebra priors no longer fall into the silent-transpose trap, llms.txt is actionable at one fetch, and external faer/ndarray memory is wrapped zero-copy.

What changed

  • New mapping page docs/getting-started/ndarray-nalgebra-mapping.md (peer of pytorch-jax-mapping.md): the column-major asymmetry (ndarray row-major dangerous, nalgebra column-major fine), crate-selection entry point, why the backend is an explicit constructed value + the construct-once-reuse idiom, an faer-vs-BLAS decision guide, .dot()matmul arity across the three API tiers, Tensor vs TypedTensor, and a zero-copy-interop section stating that adopting tenferro kernels does not require migrating tensor ownership (with the measured +10 crates / +28 s cold build from [Feature]: Guarantee downstream faer and BLAS interop with runnable tutorials #1602).
  • llms.txt: inline "Conventions you must know before writing code" block (the five conventions), republished skill-reference recipes near the top, warning-shaped descriptions for the memory-order / einsum / parallelism-and-caching trap pages, and a link back to the README as the canonical router.
  • README: the same five-line conventions block, a link to docs/llms.txt, links to the four skill-reference recipes, and the new mapping page — making it the single router to every artifact.
  • Skill references: api-cheatsheet gains a runnable "Borrowing external memory" recipe (TypedTensorView::from_slice wrapping a faer::Mat and an ndarray view, plus the TypedTensorViewMut::from_slice write-through variant); pitfalls gains per-origin traps (ndarray / nalgebra / PyTorch) and a redirect off the retired TypedStridedTensorView (Add TypedStridedTensorView for borrowed host strided tensor inputs #886). All mirrors (.claude, .kimi) kept byte-identical.
  • Tooling: build_docs_site.sh republishes the skill references; check-docs-site.py adds reachability assertions (README links llms.txt and the skill; llms.txt links the README) plus a built-site skill-references check, with tests.

Verification

  • python3 scripts/test-check-docs-site.py (new + existing checker tests)
  • python3 scripts/check-doc-snippets.py --check, check-agent-skills.py (snippet/mirror sync)
  • cargo test -p tenferro-tutorial-code (runnable interop snippet + all tutorial binaries)
  • bash scripts/build_docs_site.sh /tmp/tenferro-site-1641 — full site build, step [8/9] runs the new checks and passes; acceptance items confirmed (llms.txt lists the mapping page + cheatsheet recipe + README; site serves skill-references/*.md and the rendered mapping page).
  • bash scripts/check-pr-fast.sh --coverage-reviewed --test 'cargo test -p tenferro-tutorial-code' — passes.
  • repository-rules-review — pass (LLM review skipped, local deterministic review).

Independent GPT review of the diff was incorporated (provider-feature additivity and reinterpret-vs-transpose wording corrected; reachability check hardened to parse link targets).

…y interop (issue #1641)

- New getting-started page translating ndarray / nalgebra / ndarray-linalg
  priors: column-major asymmetry, crate selection, explicit backend values,
  faer vs BLAS provider decision guide, dot-to-matmul arity, Tensor vs
  TypedTensor, and zero-copy interop with the measured marginal cost.
- llms.txt gains the five-line conventions block, republished skill-reference
  recipes near the top, warning-shaped trap descriptions, and a link back to
  the README as the canonical router; README links llms.txt and the recipes.
- Skill references gain a borrowing-external-memory recipe (faer/ndarray wrap
  via TypedTensorView::from_slice) and per-origin traps; mirrors kept in sync.
- build_docs_site.sh republishes the skill references; check-docs-site.py
  asserts README/llms.txt reachability and built-site reference copies.
@github-actions

Copy link
Copy Markdown
Contributor

Repository rules review

Repository rules review (659830c5cad3438b9fdc7705d26b75e97afcca14...44e4e8cb6f931b42817c8644839a81d8be233529)
Verdict: pass
Findings:
- [warn] llm-skipped (External LLM Review) <unknown>: External LLM review was skipped
  External LLM review is permanently disabled; deterministic checks only.

@shinaoka
shinaoka enabled auto-merge (squash) August 10, 2026 07:05
@shinaoka
shinaoka merged commit 1458b50 into main Aug 10, 2026
25 checks passed
@shinaoka
shinaoka deleted the codex/issue-1641-onboarding branch August 10, 2026 07:34
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.

[Docs]: Harden llms.txt and onboarding for agents with Rust-ecosystem priors (ndarray/nalgebra/ndarray-linalg)

1 participant