Skip to content

docs: streamline beginner onboarding and add end-to-end examples#46

Open
zzwwji-lab wants to merge 2 commits into
RuyiAI-Stack:mainfrom
zzwwji-lab:agent/docs-beginner-onboarding
Open

docs: streamline beginner onboarding and add end-to-end examples#46
zzwwji-lab wants to merge 2 commits into
RuyiAI-Stack:mainfrom
zzwwji-lab:agent/docs-beginner-onboarding

Conversation

@zzwwji-lab

@zzwwji-lab zzwwji-lab commented Jul 14, 2026

Copy link
Copy Markdown

What changed

  • Consolidated general documentation navigation in the repository-level
    README.md; the docs/ directory no longer has a separate README.md.
  • Added separate Beginner, Kernel Developer, and Compiler Contributor routes
    to the repository README.
  • Added a linear 15-minute Host CPU quick start with a strict vector-add
    correctness check and an end-to-end explanation of the kernel, grid, mask,
    driver, and compiler stages.
  • Marked implementation, optimization, and benchmark material as advanced,
    while adding audience, prerequisites, and outcomes to the IR and debugging
    guides.
  • Added a minimal rvv_vec_add_elf.py RISC-V/QEMU tutorial and a
    repository-based operator migration case study.
  • Renamed docs/05-Operator Migration.md to
    docs/05-Operator-Migration.md, updated relative links, and normalized
    Markdown line endings to LF.

Why

The previous docs exposed several competing entry points and sent beginners
into compiler internals too early. The first Host CPU example also did not
clearly distinguish native execution from RISC-V/QEMU, and the historical
vector-add pytest printed numerical differences without asserting correctness.

This revision keeps the existing technical material but gives first-time
Triton, MLIR, and RISC-V readers one shortest path to a verified result before
introducing contributor internals.

User and developer impact

Beginners can now run and understand one complete Host CPU example before
choosing an optional RISC-V/QEMU path. Kernel developers get a concrete
migration and failure-triage workflow. Compiler contributors retain the
detailed analysis, lowering, ABI, optimization, and benchmark references in an
explicitly advanced route.

PyTorch references are described as correctness baselines rather than
Triton-RISCV fallbacks, and Host/QEMU measurements are not presented as real
RISC-V hardware performance.

Validation

  • markdownlint-cli2: 0 errors across the documentation set.
  • Custom relative-link and GitHub-style anchor checker: 110 links checked
    successfully.
  • git diff --check: passed.
  • All Markdown files checked as LF-only; CRLF was removed from the optimization
    and benchmark guides.
  • Critical paths and claims were statically checked against the current
    backend, scripts, examples, performance helpers, and CI workflow.

The Linux Triton/Buddy build and QEMU workflow were not executed from this
Windows workspace; their documented commands and success criteria were
verified against repository sources.

@zzwwji-lab
zzwwji-lab marked this pull request as ready for review July 16, 2026 06:49
@WuXintong123

Copy link
Copy Markdown
Collaborator

The docs directory should not contain a separate README.md file. If additional general information is needed, please add it to the repository’s root-level README.md instead.

@zzwwji-lab

Copy link
Copy Markdown
Author

Thanks for the review! I’ve removed docs/README.md, moved the general documentation navigation and learning paths to the root-level README.md, and updated the related links accordingly.

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.

2 participants