已合并
docs: 优化 README 结构,功能示例合并至 examples(#168) #443
docs: 优化 README 结构,功能示例合并至 examples(#168) #443
已合并
sinat_31531339创建于 7月21日
sinat_31531339
sinat_31531339成员
7月21日

描述

优化 OAM-Tools 文档结构,落实 issue #168 的三项改进,并保持中英文档同步

  1. 功能示例合并至 examples:将根 README.md 的「功能运行示例」章节(asys / msaicerr / msprof 的环境准备与命令示例)迁移至 examples/README.md,根 README 仅保留一句话导引指向 examples。

  2. 重构 examples/README.md:新增目录导航;章节结构调整为「环境准备 → 一键运行脚本 → 各组件命令示例」;将原先抽象的「样例/说明」表格升级为指向仓内真实脚本(asys/run.shmsaicerr/run.shmsprof/run.shdeploy.sh)的可点击链接,并修正描述与脚本实际行为的对应关系。

  3. 删除「相关文档」章节,链接并入核心特性表格:「核心特性」表格新增「文档」列,四个组件分别指向仓内文档(docs/zh/{asys,msaicerr,profiling,hccl_test}/README.md),替换原先的 hiascend.com 外链;删除整个「📚 相关文档」章节,其中唯一不重复的「快速安装指南」「环境变量参考」并入「相关信息」章节以免丢失链接。

  4. 英文文档同步(本仓文档成对维护)README_en.md 按上述同一结构调整(核心特性表格新增 Documentation / Examples 两列、删除 ▶️ Usage Examples📚 Related Documentation 章节、Quick Start 精简为一句导引、其余链接并入 Related Information);新增 examples/README_en.md 作为 examples/README.md 的英文版。组件用户指南目前仅有中文(docs/zh/),英文版链接指向中文文档并加说明,避免死链。

  5. 快速开始恢复为可执行步骤:原实现把「快速开始」压缩成一句导航句(「请先参考 X,随后按 Y,再参考 Z」),读者读完仍不知该敲什么命令、且要跳三个章节。按业界惯例(快速开始 = 从零到跑通的最短路径,而非导航目录)恢复为 4 步可复制命令:安装依赖 → 编译 → 安装 → 验证,并补一个可验证终点(asys -h)。参数穷举、离线编译、调试构建等仍留在「编译参数与依赖说明」,与快速开始分工。

  6. 锚点落到无 emoji 的 h3 子标题源码编译 原为一整段无子标题,按内容拆为「加载环境变量 / 执行编译 / 编译参数与依赖说明」;安装与验证 沿用既有「安装 / 验证」。h2 的 emoji 全部保留不动,锚点一律指向这些 h3,且指向语义最贴近的子节(正文「按源码编译构建」落在「执行编译」,「安装验证」分别落在两个子节)。原因见下方「锚点冲突」一节。

锚点冲突(本 PR 曾因此 FAILED 两轮)

本仓锚点要同时满足两个判定方,二者对含 emoji/ 的标题给出的 slug 不同,这两类标题没有两边皆可的写法:

标题形态 GitCode 渲染(决定网页能否跳转) 流水线 StaticCheck_link_validity(决定门禁)
## 🔧 源码编译 #源码编译 #-源码编译 ⚠️ 冲突
## asys(故障信息收集 / 诊断) #asys故障信息收集-诊断 #asys故障信息收集--诊断 ⚠️ 冲突
### 安装(纯文字) #安装 ✅ 一致
## msprof(性能调优)(有括号无 emoji 无 / #msprof性能调优 ✅ 一致

依据是门禁产物 link_validity_check.csv 的逐条对照:README.md 第 147–149 行同时含 #源码编译#安装只有前者被拒

故本 PR 让锚点只落在「两边一致」的标题上:h2 保留 emoji 但不作锚点目标,其下拆出无 emoji 的 h3 承接锚点;asys 标题的 / 改为「与」后即可正常深链,因此核心特性表「运行示例」列三个组件保持统一的深链风格。该约定已写入仓内 gitcode-pr skill(另提 PR #464)。

评审意见处理

  • @jinyingqi(major,已采纳)examples/README.md 中 9 处 ${ASCEND_INSTALL_PATH} 统一改为 ${ASCEND_HOME_PATH}。核实依据:build.sh:79ASCEND_INSTALL_PATH="${ASCEND_HOME_PATH}",该变量由 build.sh 自行派生而非 set_env.sh 导出;examples/msaicerr/run.sh:19examples/msprof/run.sh:19 亦用 ${ASCEND_INSTALL_PATH:-${ASCEND_HOME_PATH:-...}} 兜底,反证其不保证存在。英文版同步采用 ${ASCEND_HOME_PATH}
  • @newstarzj:四条意见已逐条核实并回复。其中「脚本未创建」经核实不成立(四个脚本由 ee4b95c 早已合入 master,属仓内既有文件,故不在本 PR diff 中);两条锚点死链不成立(README.md 存在 ## 📦 安装与验证#-安装与验证 为其 emoji 剥离后的锚点,同写法在 master 已广泛使用);「保留 hiascend 外链」与 issue #168 第 3 条「链接指向仓内的组件文档」的验收要求冲突,已说明理由待评审确认。

变更类型

请选择本次引入的变更类型(勾选对应项):

关联的Issue

关联 Issue #168

如何测试

  • 校验所有仓内文档链接目标存在:docs/zh/{asys,msaicerr,profiling,hccl_test}/README.mddocs/en/quick_install.mdexamples/README_en.mdCONTRIBUTING_en.mdSECURITY_en.md 均存在。
  • 校验 examples/README.md / examples/README_en.md 中相对链接(asys/run.shmsaicerr/run.shmsprof/run.shdeploy.sh../docs/zh/...../README.md / ../README_en.md)均可解析。
  • 校验中英锚点各自自洽:中文 #-源码编译#-安装与验证;英文 #-source-code-compilation#-installation-and-verification,以及 examples 英文版三个组件锚点。
  • 确认根 README 与 README_en 均已无「相关文档」/「Related Documentation」章节,章节结构完整无断链。
  • 本地全量 UT: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.mdREADME_en.mdexamples/README.md 与新增 examples/README_en.md 四个文件,不含代码逻辑变更。

likedislike
Pull Request已成功合入, 合并人@CANN-robot
(感谢 sinat_31531339 的贡献)
sinat_31531339sinat_31531339成员
7月21日 关联了issue:[Documentation|文档反馈]: 优化README结构
atomgit-bot
atomgit-bot
7月21日 评论:

变更摘要

本次 PR 针对 OAM-Tools 仓库的文档结构进行优化,落实 issue #168 的三项改进:将根 README.md 的功能示例章节迁移至 examples/README.md,重构 examples/README.md 的目录导航与内容组织,并将「相关文档」章节中的链接整合进「核心特性」表格和「相关信息」章节,同时统一使用仓内文档链接替换外部链接。

主要改动

  • 功能示例迁移至 examples/README.md:从根 README.md 中移除 asysmsaicerrmsprof 的「功能运行示例」章节(含环境准备与命令示例),仅保留一句指向 examples/ 目录的导引语句。
  • 重构 examples/README.md 结构与内容:新增目录导航,将章节调整为「环境准备 → 一键运行脚本 → 各组件命令示例」的三层结构;将原本抽象的样例说明表格升级为指向仓内真实脚本(asys/run.shmsaicerr/run.shmsprof/run.shdeploy.sh)的可点击链接,并修正描述与脚本实际行为的对应关系。
  • 「核心特性」表格新增「文档」列并删除「相关文档」章节:在核心特性表格中为四个组件新增「文档」列,分别指向仓内文档(docs/zh/asys/README.mddocs/zh/msaicerr/README.mddocs/zh/profiling/README.mddocs/zh/hccl_test/README.md);删除整个「📚 相关文档」章节,其中不重复的「快速安装指南」与「环境变量参考」链接并入「相关信息」章节。
likedislike
atomgit-bot
atomgit-bot
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 个。

整体风险评估:低风险。本次变更为文档内容的位置迁移与结构调整,不涉及可执行代码、配置、依赖或构建流程。所有外部可见的信息均被保留,唯一的问题是可修正的路径引用偏差。

⚠️ 已识别出整体风险,但无法提取行内评论,请参考整体评估。

likedislike
CANN-robotCANN-robot成员
7月21日 添加了label:cann-cla/yes
CANN-robot
CANN-robot成员
7月21日 评论:

CLA Signature Pass

sinat_31531339, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
此处折叠了188条消息 查看更多
CANN-robotCANN-robot成员
8 天前 添加了label:approved
sinat_31531339
sinat_31531339成员
8 天前 评论:
likedislike
zhangjie
zhangjie成员
8 天前 评论:

/lgtm

likedislike
CANN-robotCANN-robot成员
8 天前 添加了label:lgtm
CANN-robotCANN-robot成员
8 天前 合入了pull request