Document and verify a kernel
Keep each backend's mathematical page in <backend>/<operation>/docs/index.md
and its C++ call snippet in that page. Shared concepts belong under
docs/concepts/; do not duplicate the semantic contract or algorithm in a teaching
operation. Backend indexes link to local pages, and the exporter assembles one
portal. Public headers generate API declarations; authored pages explain
observable semantics and rationale.
For a long operation, keep the tensor contract and C++ call in index.md, then
link to operation-local numerical, implementation and validation pages. Each
rule still has one canonical explanation; do not duplicate it in the overview.
Required sections
Each operation page covers Contract, Parameters, Numerical behavior, C++ call, Memory and lifecycle, Implementation notes, and Tests and qualification.
Document admitted tensors and typed parameters before implementation choices. Include every semantically distinct path: its eligibility, arithmetic order, intermediate precision, special values, tails and fallback. Explain why it exists, but do not make a performance claim from code structure alone.
Public calls and production tests
Write a concise C++20 call snippet in each operation's ## C++ call section,
using installed public headers and real tensor specifications and parameters.
Distinguish file-scope includes/aliases from statements in the caller's function.
State omitted buffer/service setup, failure handling and storage lifetimes.
A codec call is not device execution. Do not add standalone demonstration programs,
source-insertion markers or a snippet build framework.
Link the operation's existing correctness tests and, for EV74, its device fixture. Those tests own independent numerical expectations and runnable execution coverage. Installed-package tests separately check public headers, exports and linkage; documentation snippets are not compiled or qualification evidence.
Run source validation and documentation unit tests from the repository root:
python3 tools/docs/validate.py
python3 -m unittest discover -s tests/docs -p 'test_*.py'
Diagrams and exports
Edit DOT sources in docs/assets/sources/, not generated SVGs. Captions and text
must explain the diagram without relying on color or tiny labels. Run on the
host from the repository root; Graphviz, Doxygen and Node/npm are required:
python3 tools/docs/render_diagrams.py
python3 tools/docs/validate.py
python3 tools/docs/build.py --output build/docs-export
The export contains authored pages and call snippets, public API reference and
a source/hash manifest. It is an unpublished English preview, not a deployment.
See tools/docs/README.md for local Core-theme preview and publication prerequisites.
Review diagrams in the rendered page at desktop and mobile widths, not only as standalone SVGs. Prefer compact vertical flows over wide strips; the browser check requires diagram text to remain at least 12 CSS pixels after scaling. It also checks native EV74 snippets, image loading, local code scrolling and page overflow. Operation overview coverage follows the build catalogue and authored slug automatically; no second operation list is needed. Add focused browser assertions when a page introduces a new mathematical or visual presentation.
Review numerical explanations
Use fenced math blocks for display equations and $...$ for inline mathematics.
The Core-theme preview typesets them with pinned KaTeX dependencies and local
fonts. Do not use raw \[...\] or \(...\) delimiters: Markdown does not
render them as equations. Check the rendered result at desktop and mobile widths.
Review each formula against the implementation and independent tests. Specify rounding boundaries, NaNs, infinities, signed zero, overflow, padding and output initialization where applicable. Private candidate overrides are test tools, not public parameters. Keep allocation/submission ownership outside numerical kernels.