docs(user): Add the language and operations chapters (B2)

[lyfne123]

Second batch of the user manual (see #2120). Adds the two reference chapters the manual
was missing, retires the page they replace, and adds a lint gate so the pl.* surface
cannot drift out of the docs unnoticed.

Follows #2193 (site scaffolding) and #2198 (skeleton).

What lands

docs/*/user/language/ — 7 pages ×2 languages. One page per part of the language,
each following the manual's fixed structure (Concept → Quickstart → Mechanics → Edge
Cases → See Also):

Page	Covers
00-types.md	dtypes, Tensor/Tile/Scalar/Array, layouts, dynamic shapes, parameter directions
01-functions.md	the @pl.jit family, @pl.function/@pl.program, cross-function calls
02-control-flow.md	range/parallel/unroll/pipeline/while_, loop carries, yield_, SSA
03-memory.md	the six on-chip spaces, load/store/move, valid shape and padding
04-scopes-and-tasks.md	at/cluster/spmd/split_aiv, runtime scopes, submit, deps=, predicate=
05-directives.md	static_print/static_assert, dump_tag/dumps=, pl.array, subscript sugar

docs/*/user/ops/ — 3 pages ×2 languages. Which namespace an operator belongs to
(pl.* vs pl.tensor.* vs pl.tile.*), how unified dispatch picks one, and the catalog.

Migration. 02-operation_reference.md is deleted — superseded by ops/.
01-language_guide.md is reduced to its one section not covered by language/
("Compiling a Program"), which B6 will absorb into the execution chapter. 12 inbound
links across both languages repointed.

tests/lint/check_docs_symbol_coverage.py (wired into pre-commit). Reads
pypto.language.__all__ statically via ast — pre-commit has no built extension, so
it must not import pypto — and fails when an exported symbol appears nowhere in
docs/en/user/**. Symbols belonging to unwritten chapters sit in a DEFERRED list, each
tagged with the batch that reclaims it; a DEFERRED entry that has since been
documented also fails, so the list cannot rot. It caught 13 genuine omissions while this
batch was being written.

Coverage now: 209 of 222 documentable symbols, 13 deferred to B5/B6.

Every complete example was compiled

Each fenced example that defines a full @pl.jit entry is driven through a real
ir.compile() — not lower(), which stops before code generation. 9 complete
examples, 9 compiled, 0 failures. Fragments stay fragments and are labelled as such.

This is new for the manual, and it immediately paid for itself. Three examples did not
compile:

• a 1-D tensor example rejected by codegen (tile.store tile valid_shape must be 2D);
• a @pl.jit.host example calling a function it never defined;
• a control-flow Quickstart using pl.create_tensor inside an .incore body.

The third was inherited from 01-language_guide.md — the old examples were never
compile-verified, which is how it survived. Chasing the last one surfaced two compiler
defects, filed separately as #2228 (tile-typed loop carry emits .pto that ptoas
rejects) and #2229 (unified pl.add dispatching to tensor.add for a Tile).

Rebased onto lower()

#2230 landed mid-batch and removed compile_for_test(). language/01-functions.md
(EN+ZH) is synced: the IR-inspection guidance now distinguishes lower() (post-pass
ir.Program) from compiled.program.as_python() (specialized, pre-pass), and the
"verify with a full compile" pitfall no longer names a deleted API. Each new claim was
executed rather than read off the docstring — lower(*args), argument-less lower(),
and the AttributeError on JITFunction.as_python().

Checks

• Example compilation: 9/9, against this branch's build (import origin confirmed — an
  editable-install finder had silently redirected the first run to another worktree).
• check_docs_symbol_coverage.py: exit 0.
• Link/anchor sweep over 212 pages: zero problems under user/. The 6 reported are
  pre-existing dev/passes/ headings containing &/—, where the slug approximation
  differs from python-markdown.
• check_docs_en_zh_parity / check_docs_nav / check_english_only: pass.
• mkdocs build --strict was not run locally (PyPI is unreachable from this host); the
  Docs workflow is the check for it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4627ed140

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 39885d42-8499-42d6-8725-da6df71f5c12

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The documentation is reorganized into Language Guide, Operations, and compilation chapters in English and Chinese. Navigation links are updated. A pre-commit hook now runs a symbol coverage lint tool.

Changes

Documentation architecture

Layer / File(s)	Summary
Documentation coverage lint .pre-commit-config.yaml, tests/lint/check_docs_symbol_coverage.py	A pre-commit hook runs a checker that compares public language symbols with identifiers in user Markdown code spans.
Navigation and compilation documentation mkdocs.yml, docs/*/index.md, docs/*/user/01-language_guide.md, docs/*/user/02-quickstart.md, docs/*/user/03-programming-model.md	Navigation and cross-references now use chaptered Language Guide, Operations, and compilation pages. The former language-guide pages now focus on compilation APIs and IR inspection.
Language Guide chapters docs/en/user/language/*, docs/zh/user/language/*	Added chapters for types, functions, control flow, memory, scopes and tasks, and directives, with landing pages and related references.
Operations chapter docs/en/user/ops/*, docs/zh/user/ops/*	Added namespace-selection guidance, operator catalogs, namespace rules, operator behavior, and related references.
Legacy operation references docs/en/user/02-operation_reference.md, docs/zh/user/02-operation_reference.md	Removed the former standalone operation-reference pages.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• hw-native-sys/pypto#2014: Introduced the JITFunction.compile() behavior described in the new compilation documentation.
• hw-native-sys/pypto#2165: Also restructured language documentation and scope/task cross-links.
• hw-native-sys/pypto#2193: Also changed user documentation navigation and mkdocs.yml.

Poem

A rabbit hops through docs anew,
With paths aligned and chapters true.
Symbols checked by a careful gate,
Compile notes now navigate.
“Thump!” says Bun, “the links all bloom!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the user manual language and operations chapters.
Description check	✅ Passed	The description directly explains the new chapters, documentation migration, lint gate, validation results, and related limitations.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 11

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/zh/user/language/02-control-flow.md (1)

167-167: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Remove the blank line inside the blockquote.

markdownlint-cli2 fails with MD028/no-blanks-blockquote at Line 167. Remove the blank line so the two callouts remain contiguous.

Proposed fix

 > **致命陷阱：** 一前一后写两次派发并不会让它们有序。如果那个关系没有体现为运行时能看见的缓冲区重叠，就不存在边，两个任务可能重叠执行。结果是一个偶发复现、一上调试器就消失的竞态。请用 `deps=` 把边写出来。
-
 > **致命陷阱：** 对一个生产者不在 `deps=` 里的张量使用 `predicate=`，读到的是当时恰好在那里的东西。没有任何提示 —— 任务被跳过或不被跳过，取决于陈旧数据。

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/zh/user/language/02-control-flow.md` at line 167, Remove the blank line
inside the blockquote around the two callouts in the control-flow documentation,
keeping both callouts contiguous so markdownlint rule MD028 passes.

Source: Pipeline failures

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.pre-commit-config.yaml:
- Around line 47-49: Update the Python hook configuration for
check_docs_symbol_coverage.py so language_version uses the repository’s exact
supported Python interpreter, such as python3.10, or the shared pre-commit
default if one is defined; do not leave it as the unpinned python3 value.

In `@docs/en/user/index.md`:
- Line 78: Update the “What is not here yet” section in the user documentation
index so the “Tasks, dependencies, manual_scope / submit” row is consistent with
the linked “Scopes and Tasks” chapter: move it out of the unavailable-topics
section or remove it from that list, leaving only genuinely missing topics
there.

In `@docs/en/user/language/00-types.md`:
- Line 180: Update the dependency-risk wording in
docs/en/user/language/00-types.md at lines 180-180 from “A written buffer” to “A
read-write buffer”; update docs/zh/user/language/00-types.md at lines 142-142
from “会被写入的缓冲区” to “读写缓冲区”. Keep the guidance specific to buffers the kernel
both reads and writes, while preserving Out as valid for write-only output.

In `@docs/en/user/language/01-functions.md`:
- Line 70: Update the function-style tables in
docs/en/user/language/01-functions.md at lines 70-70 and
docs/zh/user/language/01-functions.md at lines 58-58 by adding the missing
first-column header and aligning the delimiter pipes with the corresponding
English and Chinese headers; preserve the remaining table columns and content.

In `@docs/en/user/language/03-memory.md`:
- Line 147: Clarify the memory documentation table row for `pl.matmul` by
specifying that the `Left`/`Right` operand restriction applies to tile-level
`pl.matmul`. Keep the tensor-level behavior described earlier, or explicitly
distinguish both supported overloads so the documentation is not contradictory.

In `@docs/en/user/language/04-scopes-and-tasks.md`:
- Line 219: Remove the blank line inside the blockquote around the two
fatal-pitfall paragraphs in the scopes-and-tasks documentation, or prefix that
line with “>” so the blockquote remains continuous and passes
MD028/no-blanks-blockquote.

In `@docs/en/user/ops/00-dispatch.md`:
- Around line 59-63: Update the read/write operation references to use the
tensor-only namespace consistently: keep docs/en/user/ops/00-dispatch.md lines
59-63 as pl.tensor.read / pl.tensor.write, and change
docs/en/user/ops/01-catalog.md line 123 from the generic pl. spelling to
pl.tensor.read / pl.tensor.write. No other operation entries require changes.

In `@docs/en/user/ops/01-catalog.md`:
- Around line 103-105: Replace the placeholder quote descriptions in the
`row_expand_div`/`row_expand_max`/`row_expand_min` and
`col_expand_div`/`col_expand_max`/`col_expand_min` table rows with explicit
descriptions of the broadcast-fused division, maximum, and minimum operations,
preserving the existing descriptions for addition, subtraction, and
multiplication.

In `@docs/zh/user/01-language_guide.md`:
- Line 27: Update the dump_passes entry in the language guide table to document
that the API accepts both bool shorthand and PassDumpLevel, including that True
maps to CONCISE and False maps to NONE; keep the existing dump-directory
behavior description.
- Line 60: Update the compile() documentation statement to describe unsupported
keyword arguments such as skip_ptoas as invalid input that raises an error
during JITFunction.compile() signature binding, rather than saying they are
silently ignored; retain the guidance to pass compilation options through
config=RunConfig(...).

In `@docs/zh/user/index.md`:
- Line 71: Remove the row referencing `language/04-scopes-and-tasks.md` from the
deferred-content table in the user documentation, or relocate it to the
directory/capabilities section so the table contains only topics still excluded
from the user manual.

---

Outside diff comments:
In `@docs/zh/user/language/02-control-flow.md`:
- Line 167: Remove the blank line inside the blockquote around the two callouts
in the control-flow documentation, keeping both callouts contiguous so
markdownlint rule MD028 passes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: de768f8d-f620-4027-8d8e-aad3a471d540

📥 Commits

Reviewing files that changed from the base of the PR and between 6234d0e and c4627ed.

📒 Files selected for processing (39)

• .pre-commit-config.yaml
• docs/en/dev/language/00-python_syntax.md
• docs/en/dev/language/index.md
• docs/en/index.md
• docs/en/user/01-language_guide.md
• docs/en/user/02-operation_reference.md
• docs/en/user/02-quickstart.md
• docs/en/user/03-programming-model.md
• docs/en/user/index.md
• docs/en/user/language/00-types.md
• docs/en/user/language/01-functions.md
• docs/en/user/language/02-control-flow.md
• docs/en/user/language/03-memory.md
• docs/en/user/language/04-scopes-and-tasks.md
• docs/en/user/language/05-directives.md
• docs/en/user/language/index.md
• docs/en/user/ops/00-dispatch.md
• docs/en/user/ops/01-catalog.md
• docs/en/user/ops/index.md
• docs/zh/dev/language/00-python_syntax.md
• docs/zh/dev/language/index.md
• docs/zh/index.md
• docs/zh/user/01-language_guide.md
• docs/zh/user/02-operation_reference.md
• docs/zh/user/02-quickstart.md
• docs/zh/user/03-programming-model.md
• docs/zh/user/index.md
• docs/zh/user/language/00-types.md
• docs/zh/user/language/01-functions.md
• docs/zh/user/language/02-control-flow.md
• docs/zh/user/language/03-memory.md
• docs/zh/user/language/04-scopes-and-tasks.md
• docs/zh/user/language/05-directives.md
• docs/zh/user/language/index.md
• docs/zh/user/ops/00-dispatch.md
• docs/zh/user/ops/01-catalog.md
• docs/zh/user/ops/index.md
• mkdocs.yml
• tests/lint/check_docs_symbol_coverage.py

💤 Files with no reviewable changes (2)

• docs/en/user/02-operation_reference.md
• docs/zh/user/02-operation_reference.md