Documentation Workflow

RukaLang documentation sync is enforced with executable checks:

  • cargo test --doc validates Rust doc examples.
  • cargo test validates rk code fences in documentation chapters.
  • npm --prefix web run test:wasm-api validates browser WASM API smoke behavior.
  • mdbook build docs ensures the book renders.
  • mdbook test docs compiles runnable Rust snippets in the book.
  • mdbook-linkcheck --standalone docs fails on broken links.

For feature changes:

  1. Update API docs near code using /// and //! where relevant.
  2. Update guide/reference pages in the docs source tree when behavior changes.
  3. Keep command examples aligned with cargo run -- --help and tests.

RukaLang snippet fences use these tags:

  • rk: example must compile.
  • rk,run: example must compile and run.
  • rk,fail: example must fail to compile.

Rustdoc link convention for mdBook pages:

  • Use path-relative links rooted at ../../rustdoc/ from docs chapters.
  • Prefer reference-style links at the bottom of the page for readability.
  • Example:
    • in text: [`LowerMirPass`][rustdoc-lower-mir-pass]
    • link target: [rustdoc-lower-mir-pass]: ../../rustdoc/rukalang/driver/passes/struct.LowerMirPass.html

If a change intentionally requires no docs updates, explain why in the pull request.

Run docs checks locally:

mdbook build docs
mdbook test docs
mdbook-linkcheck --standalone docs

./scripts/ci.sh includes these checks.