已合并
docs: 优化 README 结构,功能示例合并至 examples(#168) #443
sinat_31531339创建于 7月21日
docs: 优化 README 结构,功能示例合并至 examples(#168) #443
已合并
Pull Request已成功合入, 合并人@CANN-robot
(感谢 sinat_31531339 的贡献)7月21日 关联了issue:[Documentation|文档反馈]: 优化README结构
atomgit-bot
7月21日 评论:
7月21日 评论:
变更摘要
本次 PR 针对 OAM-Tools 仓库的文档结构进行优化,落实 issue #168 的三项改进:将根 README.md 的功能示例章节迁移至 examples/README.md,重构 examples/README.md 的目录导航与内容组织,并将「相关文档」章节中的链接整合进「核心特性」表格和「相关信息」章节,同时统一使用仓内文档链接替换外部链接。
主要改动
- 功能示例迁移至
examples/README.md:从根README.md中移除asys、msaicerr、msprof的「功能运行示例」章节(含环境准备与命令示例),仅保留一句指向examples/目录的导引语句。 - 重构
examples/README.md结构与内容:新增目录导航,将章节调整为「环境准备 → 一键运行脚本 → 各组件命令示例」的三层结构;将原本抽象的样例说明表格升级为指向仓内真实脚本(asys/run.sh、msaicerr/run.sh、msprof/run.sh、deploy.sh)的可点击链接,并修正描述与脚本实际行为的对应关系。 - 「核心特性」表格新增「文档」列并删除「相关文档」章节:在核心特性表格中为四个组件新增「文档」列,分别指向仓内文档(
docs/zh/asys/README.md、docs/zh/msaicerr/README.md、docs/zh/profiling/README.md、docs/zh/hccl_test/README.md);删除整个「📚 相关文档」章节,其中不重复的「快速安装指南」与「环境变量参考」链接并入「相关信息」章节。


atomgit-bot
7月21日 评论:
7月21日 评论:
代码审查
审查总结
本次 diff 为纯文档重构,涉及 2 个文件:
-
README.md — 已审查,无严重问题。变更包括:核心特性表格新增「文档」列指向仓内用户指南;「功能运行示例」章节精简为一句话导引;删除「相关文档」章节并将其中唯一不重复的链接并入「相关信息」章节。所有新增/保留的仓内链接均验证目标文件存在。
-
examples/README.md — 已审查,发现 1 个 P3 级别问题。变更包括:章节重构(新增目录、环境准备、一键运行脚本、各组件命令示例);从根 README 迁入的详细示例内容中,5 处内联代码路径引用未适配子目录上下文(
src/...应为../src/...,build/...应为../build/...)。这些是反引号内联代码而非可点击链接,实际影响较低。
按优先级统计:P0 0 个,P1 0 个,P2 0 个,P3 1 个。
整体风险评估:低风险。本次变更为文档内容的位置迁移与结构调整,不涉及可执行代码、配置、依赖或构建流程。所有外部可见的信息均被保留,唯一的问题是可修正的路径引用偏差。
⚠️ 已识别出整体风险,但无法提取行内评论,请参考整体评估。


7月21日 添加了label:cann-cla/yes
CANN-robot
7月21日 评论:
7月21日 评论:
此处折叠了188条消息 查看更多
8 天前 添加了label:approved
sinat_31531339
8 天前 评论:
8 天前 评论:
zhangjie
8 天前 评论:
8 天前 评论:
/lgtm


8 天前 添加了label:lgtm
8 天前 合入了pull request
描述
优化 OAM-Tools 文档结构,落实 issue #168 的三项改进,并保持中英文档同步:
功能示例合并至 examples:将根
README.md的「功能运行示例」章节(asys / msaicerr / msprof 的环境准备与命令示例)迁移至examples/README.md,根 README 仅保留一句话导引指向 examples。重构 examples/README.md:新增目录导航;章节结构调整为「环境准备 → 一键运行脚本 → 各组件命令示例」;将原先抽象的「样例/说明」表格升级为指向仓内真实脚本(
asys/run.sh、msaicerr/run.sh、msprof/run.sh、deploy.sh)的可点击链接,并修正描述与脚本实际行为的对应关系。删除「相关文档」章节,链接并入核心特性表格:「核心特性」表格新增「文档」列,四个组件分别指向仓内文档(
docs/zh/{asys,msaicerr,profiling,hccl_test}/README.md),替换原先的 hiascend.com 外链;删除整个「📚 相关文档」章节,其中唯一不重复的「快速安装指南」「环境变量参考」并入「相关信息」章节以免丢失链接。英文文档同步(本仓文档成对维护):
README_en.md按上述同一结构调整(核心特性表格新增 Documentation / Examples 两列、删除▶️ Usage Examples与📚 Related Documentation章节、Quick Start 精简为一句导引、其余链接并入 Related Information);新增examples/README_en.md作为examples/README.md的英文版。组件用户指南目前仅有中文(docs/zh/),英文版链接指向中文文档并加说明,避免死链。快速开始恢复为可执行步骤:原实现把「快速开始」压缩成一句导航句(「请先参考 X,随后按 Y,再参考 Z」),读者读完仍不知该敲什么命令、且要跳三个章节。按业界惯例(快速开始 = 从零到跑通的最短路径,而非导航目录)恢复为 4 步可复制命令:安装依赖 → 编译 → 安装 → 验证,并补一个可验证终点(
asys -h)。参数穷举、离线编译、调试构建等仍留在「编译参数与依赖说明」,与快速开始分工。锚点落到无 emoji 的 h3 子标题:
源码编译原为一整段无子标题,按内容拆为「加载环境变量 / 执行编译 / 编译参数与依赖说明」;安装与验证沿用既有「安装 / 验证」。h2 的 emoji 全部保留不动,锚点一律指向这些 h3,且指向语义最贴近的子节(正文「按源码编译构建」落在「执行编译」,「安装与验证」分别落在两个子节)。原因见下方「锚点冲突」一节。锚点冲突(本 PR 曾因此 FAILED 两轮)
本仓锚点要同时满足两个判定方,二者对含 emoji 与含
/的标题给出的 slug 不同,这两类标题没有两边皆可的写法:StaticCheck_link_validity(决定门禁)## 🔧 源码编译#源码编译#-源码编译## asys(故障信息收集 / 诊断)#asys故障信息收集-诊断#asys故障信息收集--诊断### 安装(纯文字)#安装## msprof(性能调优)(有括号无 emoji 无/)#msprof性能调优依据是门禁产物
link_validity_check.csv的逐条对照:README.md第 147–149 行同时含#源码编译与#安装,只有前者被拒。故本 PR 让锚点只落在「两边一致」的标题上:h2 保留 emoji 但不作锚点目标,其下拆出无 emoji 的 h3 承接锚点;asys 标题的
/改为「与」后即可正常深链,因此核心特性表「运行示例」列三个组件保持统一的深链风格。该约定已写入仓内gitcode-prskill(另提 PR #464)。评审意见处理
examples/README.md中 9 处${ASCEND_INSTALL_PATH}统一改为${ASCEND_HOME_PATH}。核实依据:build.sh:79为ASCEND_INSTALL_PATH="${ASCEND_HOME_PATH}",该变量由 build.sh 自行派生而非set_env.sh导出;examples/msaicerr/run.sh:19、examples/msprof/run.sh:19亦用${ASCEND_INSTALL_PATH:-${ASCEND_HOME_PATH:-...}}兜底,反证其不保证存在。英文版同步采用${ASCEND_HOME_PATH}。ee4b95c早已合入 master,属仓内既有文件,故不在本 PR diff 中);两条锚点死链不成立(README.md存在## 📦 安装与验证,#-安装与验证为其 emoji 剥离后的锚点,同写法在 master 已广泛使用);「保留 hiascend 外链」与 issue #168 第 3 条「链接指向仓内的组件文档」的验收要求冲突,已说明理由待评审确认。变更类型
请选择本次引入的变更类型(勾选对应项):
关联的Issue
关联 Issue #168
如何测试
docs/zh/{asys,msaicerr,profiling,hccl_test}/README.md、docs/en/quick_install.md、examples/README_en.md、CONTRIBUTING_en.md、SECURITY_en.md均存在。examples/README.md/examples/README_en.md中相对链接(asys/run.sh、msaicerr/run.sh、msprof/run.sh、deploy.sh、../docs/zh/...、../README.md/../README_en.md)均可解析。#-源码编译、#-安装与验证;英文#-source-code-compilation、#-installation-and-verification,以及 examples 英文版三个组件锚点。python3 -m pytest test/ut/asys/ test/ut/msaicerr/ -q→ 1104 passed(test_compile_op_ascend950.py::test_get_ub_size_not_tbe为存量失败,在未含本 PR 改动的干净工作区复跑同样失败,与本次纯文档改动无关)。msprof gtest 需编译,本地未覆盖,依赖云端UT_Test。核对清单
其他信息
本次为纯文档改动,涉及
README.md、README_en.md、examples/README.md与新增examples/README_en.md四个文件,不含代码逻辑变更。