hicann 是 CANN 社区的「骨架」——社区官网、文档站点、API 参考、博客系统、用户反馈管道——这些都不是 GitHub 原生提供的。hicann 用一套静态站点生成器 CI/CD 管道 自动部署流程把这些社区基础架构从代码仓库自动生成并部署到线上。hicann 的职责社区网站和数据管道hicann 不维护算子代码——它维护的是「社区的门面」和「信息流通的管道」hicann 架构 ├─ 静态站点生成Hugo / Docusaurus │ ├─ 官网https://www.hiascend.com/cann │ ├─ 文档站点https://www.hiascend.com/document │ └─ API 参考从代码注释自动生成 │ ├─ 内容管道 │ ├─ Markdown → HTML文档渲染 │ ├─ Doxygen → 静态 API 文档C 头文件注释 │ └─ Jupyter → 交互式教程在线运行代码 │ ├─ CI/CD 管道 │ ├─ 代码推送 → 自动构建 → 自动部署GitHub Actions │ ├─ 链接检查检查所有文档链接是否有效 │ └─ 多语言翻译管道中文 ↔ 英文 │ └─ 反馈管道 ├─ GitHub Issues → 自动分发给对应仓库的负责人 ├─ 论坛部分部署在 hicann 下 └─ 问卷调查用户反馈收集文档站点的构建流程CANN 的文档分布在 55 个 GitHub 仓库里——每个仓库有自己的 README.md、docs/ 文件夹、API 注释。hicann 聚合所有这些分散的文档生成一个统一的多页面站点。# hicann/config/site.yaml# 定义站点的结构哪些页面、从哪里拉内容site:title:昇腾CANN 开源社区base_url:https://www.hiascend.com/cann# 导航菜单nav:-title:快速开始items:-label:安装指南source:cann/community/docs/install.md# 从 community 仓库取内容-label:第一个算子source:cann/cann-samples/docs/first-op.md# 从 cann-samples 仓库取内容-title:算子库items:-label:核心算子source:cann/ops-nn/README.md-label:Transformer 算子source:cann/ops-transformer/README.md# ... 55 个仓库各有一个入口-title:工具与开发items:-label:Ascend C 编程指南source:cann/cann-learning-hub/docs/ascend-c-guide.md-label:性能调优source:cann/asc-tools/docs/tuning-guide.md# 多语言配置languages:-code:zh-CNtitle:简体中文-code:entitle:English# 侧边栏自动生成从 docs/ 目录的 _sidebar.mdsidebar:auto_generate:truemax_depth:3构建时hicann 的 CI 流水线做这些事# hicann 的构建脚本CI 中自动执行# Step 1从 55 个仓库拉取最新的 Markdown 文档forrepoinops-nn ops-transformer ge runtime cann-samples...;dogitclone--depth1https://atomgit.com/cann/$repo/tmp/sources/$repodone# Step 2渲染 Markdown → HTML用 Docusaurusnpx docusaurus build\--confighicann/config/site.yaml\--out-dir/tmp/site# Step 3API 参考生成Doxygen Breathedoxygen hicann/config/Doxyfile# 从 55 个仓库的 C 头文件注释生成 API 文档# Step 4链接检查npx broken-link-checker /tmp/site--recursive--ordered# 输出# OK: 1,234 links checked# Broken links: 3# /docs/ops-transformer/flash-attn.md → ops-transformer/examples/flash_attn.py (404)# Step 5部署到 CDN腾讯云 OSS CDNaliyun osscp/tmp/site oss://hiascend-cann-site/--recursiveAPI 文档生成从代码注释到静态站点CANN 的算子库有大量的 C kernel 代码~50,000 行。每个 kernel 函数的注释用 Doxygen 格式写——hicann 自动把这些注释编译成 HTML API 文档。// ops-nn/kernels/matmul.cpp/** * brief 矩阵乘法的 Ascend C 实现 * * 在 Cube 单元上执行 C alpha * A * B beta * C * * param A 输入矩阵 [M, K]FP16 * param B 输入矩阵 [K, N]FP16 * param C 输出矩阵 [M, N]FP16支持 in-place * param M 矩阵 A 的行数 * param N 矩阵 B 的列数 * param K 矩阵 A 的列数 矩阵 B 的行数 * param alpha 缩放因子默认 1.0 * param beta 累加因子默认 0.0表示 C 初始化为 0 * * note M、N、K 必须是 16 的倍数tiling 对齐约束 * warning FP16 精度下K 16384 时累加误差可能超过 1e-3 * * code{.cpp} * MatMulfloat16(A, B, C, 512, 512, 1024); * // C A × Btile size 16×16×16 * endcode * * see ops-blas/GEMM for higher-performance BLAS-compatible version */templatetypenameT__aicore__voidMatMul(GlobalTensorTA,GlobalTensorTB,GlobalTensorTC,intM,intN,intK,floatalpha1.0f,floatbeta0.0f);Doxygen 从这个注释生成MatMul (API Reference) Function: MatMulT(A, B, C, M, N, K, alpha1.0, beta0.0) Description: 矩阵乘法的 Ascend C 实现。在 Cube 单元上执行 C alpha * A * B beta * C Parameters: A 输入矩阵 [M, K] (FP16) B 输入矩阵 [K, N] (FP16) C 输出矩阵 [M, N] (FP16, supports in-place) ... Notes: M, N, K must be multiples of 16 Warnings: K 16384 may cause FP16 accumulation error 1e-3 Example: MatMulfloat16(A, B, C, 512, 512, 1024); See Also: ops-blas/GEMM for BLAS-compatible version多语言翻译管道CANN 社区的文档是中文写的但国际用户需要英文版本。hicann 提供翻译管道# hicann/config/translation.yamltranslation:# 翻译源source_lang:zh-CNtarget_langs:[en]# 翻译策略strategy:# 核心文档人工翻译PR 审查core_docs:-getting-started.md-install-guide.mdtranslator:manualreview_required:true# API 文档机器翻译 人工校对api_docs:translator:machinemachine_reviewengine:deepseek# 用 AI 翻译review_required:false# 博客/新闻不翻译仅中文blog:translator:skip# 翻译质量检查quality_check:# 检查英文文档是否遗漏中文原文的章节check_structure:true# 检查代码块是否在翻译中被移除keep_code_blocks:true踩坑一Static Site Generator 在中文 URL 上的问题hicann 的 Docusaurus 默认把 Markdown 文件名中文映射为 URL 路径。快速开始.md→/cann/快速开始。但 URL 中中文在部分浏览器Safari 旧版会乱码。修复配置 URL 的 slug 映射。# hicann/config/site.yamlslug_mapping:快速开始:quick-start算子库:operator-library性能调优:performance-tuningMarkdown 文件里的slug: quick-start由编辑器自动设置CI 检查 slug 映射是否覆盖所有页面。踩坑二Doxygen 对 Ascend C 宏的展开失败Ascend C 里有大量宏__aicore__、GlobalTensor、localTensor。Doxygen 不认识这些宏展开失败——API 文档中缺失类型信息。修复在 Doxygen 配置中预定义这些宏。# hicann/config/Doxyfile PREDEFINED \ __aicore__ \ GlobalTensor(x)GlobalTensor x \ localTensor(x)LocalTensor x \ ASCENDC_KERNEL \ ASCENDC_OP_REGISTER(op,name)预定义后的 API 文档GlobalTensorT A而不是空白。踩坑三GitHub Pages 的多仓库构建超时55 个仓库的克隆 Markdown 渲染 Doxygen 编译——CI 构建耗时 15-20 分钟。GitHub Actions 的时间限制是 6 小时不会超时——但 CDN 的部署需要构建产物20 分钟的构建延迟意味着文档更新不是实时的。缓解增量构建——只更新变化的仓库。# 增量构建不是全量 clone# 检查各仓库的最后 commit 时间forrepoin${REPOS[]};doLAST_BUILD$(cat/tmp/site-build-cache/$repo.last)LATEST_COMMIT$(gitls-remote https://atomgit.com/cann/$repo HEAD|cut-f1)if[$LAST_BUILD!$LATEST_COMMIT];thengitclone--depth1https://atomgit.com/cann/$repo/tmp/sources/$repoecho$LATEST_COMMIT/tmp/site-build-cache/$repo.lastCHANGED_REPOS($repo)fidone# 只为变化的仓库更新 HTML 页面forrepoin${CHANGED_REPOS[]};dobuild_pages_for_repo/tmp/sources/$repodone# 典型的增量构建耗时30 秒vs 全量构建 20 分钟55 个仓库的代码写好了但如果开发者找不到在哪里、看不懂 API 文档、找不到快速测试——代码写再多也没有用。hicann 是社区的基础架构层——从 WEB 站点到 API 文档到内容管道到 CI/CD——提供上线和运行中必须的技术骨架。底层是 Markdown/Doxygen/Docusaurus 等专业工具的组合——需要组合成一个有可靠工程的自动化流水线。
