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-CN"
      title: "简体中文"
    - code: "en"
      title: "English"

  # 侧边栏自动生成（从 docs/ 目录的 _sidebar.md）
  sidebar:
    auto_generate: true
    max_depth: 3

构建时，hicann 的 CI 流水线做这些事：

# hicann 的构建脚本（CI 中自动执行）

# Step 1：从 55 个仓库拉取最新的 Markdown 文档
for repo in ops-nn ops-transformer ge runtime cann-samples ... ; do
    git clone --depth=1 https://atomgit.com/cann/$repo /tmp/sources/$repo
done

# Step 2：渲染 Markdown → HTML（用 Docusaurus）
npx docusaurus build \
    --config=hicann/config/site.yaml \
    --out-dir=/tmp/site

# Step 3：API 参考生成（Doxygen + Breathe）
doxygen 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 + CDN）
aliyun oss cp /tmp/site oss://hiascend-cann-site/ --recursive

API 文档生成（从代码注释到静态站点）

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}
 *   MatMul<float16>(A, B, C, 512, 512, 1024);
 *   // C = A × B，tile size = 16×16×16
 * @endcode
 *
 * @see ops-blas/GEMM for higher-performance BLAS-compatible version
 */
template <typename T>
__aicore__ void MatMul(
    GlobalTensor<T>& A,
    GlobalTensor<T>& B,
    GlobalTensor<T>& C,
    int M, int N, int K,
    float alpha = 1.0f,
    float beta = 0.0f
);

Doxygen 从这个注释生成：

MatMul (API Reference)

Function: MatMul<T>(A, B, C, M, N, K, alpha=1.0, beta=0.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:
  MatMul<float16>(A, B, C, 512, 512, 1024);

See Also:
  ops-blas/GEMM for BLAS-compatible version

多语言翻译管道

CANN 社区的文档是中文写的，但国际用户需要英文版本。hicann 提供翻译管道：

# hicann/config/translation.yaml

translation:
  # 翻译源
  source_lang: "zh-CN"
  target_langs: ["en"]

  # 翻译策略
  strategy:
    # 核心文档：人工翻译（PR 审查）
    core_docs:
      - "getting-started.md"
      - "install-guide.md"
      translator: "manual"
      review_required: true

    # API 文档：机器翻译 + 人工校对
    api_docs:
      translator: "machine+machine_review"
      engine: "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.yaml
slug_mapping:
  "快速开始": "quick-start"
  "算子库": "operator-library"
  "性能调优": "performance-tuning"

Markdown 文件里的 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 文档：GlobalTensor<T>& A 而不是空白。

踩坑三：GitHub Pages 的多仓库构建超时

55 个仓库的克隆 + Markdown 渲染 + Doxygen 编译——CI 构建耗时 15-20 分钟。GitHub Actions 的时间限制是 6 小时，不会超时——但 CDN 的部署需要构建产物，20 分钟的构建延迟意味着文档更新不是实时的。

缓解：增量构建——只更新变化的仓库。

# 增量构建（不是全量 clone）
# 检查各仓库的最后 commit 时间
for repo in ${REPOS[@]}; do
    LAST_BUILD=$(cat /tmp/site-build-cache/$repo.last)
    LATEST_COMMIT=$(git ls-remote https://atomgit.com/cann/$repo HEAD | cut -f1)
    if [ "$LAST_BUILD" != "$LATEST_COMMIT" ]; then
        git clone --depth=1 https://atomgit.com/cann/$repo /tmp/sources/$repo
        echo "$LATEST_COMMIT" > /tmp/site-build-cache/$repo.last
        CHANGED_REPOS+=($repo)
    fi
done

# 只为变化的仓库更新 HTML 页面
for repo in ${CHANGED_REPOS[@]}; do
    build_pages_for_repo "/tmp/sources/$repo"
done

# 典型的增量构建耗时：30 秒（vs 全量构建 20 分钟）

---

55 个仓库的代码写好了，但如果开发者找不到在哪里、看不懂 API 文档、找不到快速测试——代码写再多也没有用。hicann 是社区的基础架构层——从 WEB 站点到 API 文档到内容管道到 CI/CD——提供上线和运行中必须的技术骨架。底层是 Markdown/Doxygen/Docusaurus 等专业工具的组合——需要组合成一个有可靠工程的自动化流水线。