[codex] Finish repo docs navigation and Chinese manual closure#91
Open
[codex] Finish repo docs navigation and Chinese manual closure#91
Conversation
This packages the outstanding local documentation work from the Cursor README/navigation lane together with the Chinese ISA cleanup already in progress. The result is a repo-wide pass over README entrypoints, docs/isa source pages, and the mirrored MkDocs source tree so the reader path is more consistent and the modified pages stop sending users into dead or unnecessary English-only jumps. Constraint: Submit the full local documentation worktree except local tool state under .omx Constraint: Keep docs/isa as the source-of-truth manual while preserving the existing MkDocs build output shape Rejected: Split the local work into smaller PRs | would strand half-finished navigation and bilingual closure fixes across the repo Confidence: medium Scope-risk: broad Reversibility: clean Directive: Keep Chinese entrypoints closed under Chinese navigation where equivalents exist, and do not reintroduce stale ops/README paths after the manual tree split Tested: python -m pre_commit run on staged files; git diff --check --cached; mkdocs strict build; changed-file markdown link scan; changed-file zh-to-en closure scan Not-tested: GitHub Actions on the rebased PR branch; live GitHub Pages after this new branch lands
zhoubot
force-pushed
the
codex/cursor-trieve-doc-nav-finish
branch
from
fdcd4e8 to
5eb67f8
Compare
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly restructures and standardizes the documentation for the PTO Tile Library, including the main README, demo guides, and the comprehensive ISA reference. The changes introduce a clearer five-layer documentation structure, task-based navigation, and a consistent format for all instruction pages. Feedback from the review identifies several typos in instruction names (specifically 'TSCATTER' being misspelled as 'TSCATTLER') and a broken anchor link in the Chinese README.
| [](LICENSE) | ||
| [](#️-平台支持) | ||
| [](docs/README_zh.md) | ||
| [](#-平台支持) |
There was a problem hiding this comment.
The anchor link #-平台支持 appears to be incorrect. Since the target header was changed to ## 平台支持 (line 156), the anchor should be #平台支持. The current link with a hyphen will likely break navigation.
Suggested change
| [](#-平台支持) | |
| [! [Platform](https://img.shields.io/badge/Platform-Ascend%20A2%20%7C%20A3%20%7C%20A5%20%7C%20CPU-green.svg)](#平台支持) |
| Tile 指令集 | ||
| ├── 同步与配置 → tassign、tsync、tsetf32mode、tsetfmatrix、tset_img2col_*、tsubview、tget_scale_addr | ||
| ├── 逐元素 Tile-Tile → tadd、tsub、tmul、tdiv、tmin、tmax、tcmp、tcvt、tsel、tlog、trecip、texp、tsqrt、trsqrt、trem、tfmod、tabs、tand、tor、txor、tnot、tneg、tprelu、taddc、tsubc、tshl、tshr | ||
| ├── Tile-标量与立即数 → tadds、tsubs、tmuls、tdi等等vs、tcmps、tsels、texpands、tfmods、trems、tands、tors、txors、tshls、tshrs、tlrelu、taddsc、tsubsc |
There was a problem hiding this comment.
Typo in the instruction list: tdi等等vs should be tdivs. This appears to be an IME conversion error where "v" was replaced with "等等" (etc.).
Suggested change
| ├── Tile-标量与立即数 → tadds、tsubs、tmuls、tdi等等vs、tcmps、tsels、texpands、tfmods、trems、tands、tors、txors、tshls、tshrs、tlrelu、taddsc、tsubsc | |
| ├── Tile-标量与立即数 → tadds、tsubs、tmuls、tdivs、tcmps、tsels、texpands、tfmods、trems、tands、tors、txors、tshls、tshrs、tlrelu、taddsc、tsubsc |
| ## Related Ops / Instruction Set Links | ||
|
|
||
| - Communication overview: [Communication and Runtime](../other/communication-and-runtime.md) | ||
| - Collective operations: [TGET](./TGET.md), [TPUT](./TPUT.md), [TREDUCE](./TREDUCE.md), [TSCATTLER](./TSCATTER.md), [TGATHER](./TGATHER.md) |
There was a problem hiding this comment.
Typo in the related operations list: TSCATTLER should be TSCATTER. This typo is recurring across multiple communication documentation files in this PR.
Suggested change
| - Collective operations: [TGET](./TGET.md), [TPUT](./TPUT.md), [TREDUCE](./TREDUCE.md), [TSCATTLER](./TSCATTER.md), [TGATHER](./TGATHER.md) | |
| - Collective operations: [TGET](./TGET.md), [TPUT](./TPUT.md), [TREDUCE](./TREDUCE.md), [TSCATTER](./TSCATTER.md), [TGATHER](./TGATHER.md) |
| - [TGATHER](./TGATHER_zh.md) | ||
| - [TSCATTER](./TSCATTER_zh.md) | ||
| - 通信概述：[通信与运行时](../other/communication-and-runtime_zh.md) | ||
| - 集合通信：[TGATHER](./TGATHER_zh.md)、[TSCATTLER](./TSCATTER_zh.md)、[TREDUCE](./TREDUCE_zh.md) |
There was a problem hiding this comment.
Typo in the related operations list: TSCATTLER should be TSCATTER.
Suggested change
| - 集合通信：[TGATHER](./TGATHER_zh.md)、[TSCATTLER](./TSCATTER_zh.md)、[TREDUCE](./TREDUCE_zh.md) | |
| - 集合通信：[TGATHER](./TGATHER_zh.md)、[TSCATTER](./TSCATTER_zh.md)、[TREDUCE](./TREDUCE_zh.md) |
| - 若 `TileData` 具有静态 `ValidCol`，`GetShape(DIM_4)` 必须能被 `ValidCol` 整除。如需支持不足整列，应使用动态 `ValidCol` 的 Tile | ||
|
|
||
| ## 目标Profile限制 | ||
|
|
There was a problem hiding this comment.
Typo in the instruction name: TSCATTLER should be TSCATTER.
Suggested change
| - `TSCATTER` 需要正确初始化的 `ParallelGroup`，覆盖所有参与的 NPU。 |
| - 逆操作：[TGATHER](./TGATHER_zh.md) | ||
| - 集合通信：[TBROADCAST](./TBROADCAST_zh.md)、[TGATHER](./TGATHER_zh.md)、[TREDUCE](./TREDUCE_zh.md) | ||
| - 点对点通信：[TGET](./TGET_zh.md)、[TPUT](./TPUT_zh.md) | ||
| - 指令集：[其他与通信](../other/README_zh.md) |
There was a problem hiding this comment.
Typo in the related operations list: TSCATTLER should be TSCATTER.
Suggested change
| - 指令集：[其他与通信](../other/README_zh.md) | |
| - 集合通信：[TBROADCAST](./TBROADCAST_zh.md)、[TGATHER](./TGATHER_zh.md)、[TSCATTER](./TSCATTER_zh.md)、[TREDUCE](./TREDUCE_zh.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
This PR packages the outstanding local documentation work from the Cursor repo-README and navigation lane.
It finishes a broad documentation pass across repo-level entrypoints, the PTO ISA manual source tree, and the mirrored MkDocs source tree. The main goals are:
Why
The local worktree had accumulated a large set of doc and README updates, but readers could still hit dead links or get bounced into English pages from Chinese entrypoints. There was also stale duplicated MkDocs source content left in a half-migrated state.
This PR lands the whole local documentation pass together so the navigation model, source tree, and rendered site stop drifting independently.
Scope highlights
docs/,demos/,include/pto/,kernels/,tests/docs/mkdocs/src/docs/isa/that no longer match the maintained source treedocs/isa/vector/micro-instruction-summary.mdValidation
./.venv-mkdocs/bin/python -m pre_commit run --files <staged-files>git diff --check --cached./.venv-mkdocs/bin/python -m mkdocs build -f docs/mkdocs/mkdocs.yml --strictzh -> enregressions where_zhequivalents existRisks
docs/mkdocs/src/docs/isa/, so reviewer attention should focus on documentation layout and publishing behavior rather than runtime code.omx/local tool state is intentionally excluded from the PR