Modernize documentation workflow

.github/workflows/docs.yml

@@ -6,97 +6,67 @@ on:
       - main
       - master
     paths:
-      - 'src/**'
-      - 'spi/**'
-      - 'scripts/**'
-      - 'overrides/**'
-      - 'mkdocs.yml'
-      - 'requirements.txt'
-      - '.github/workflows/docs.yml'
+      - "src/**"
+      - "spi/**"
+      - "scripts/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+
   pull_request:
     branches:
       - main
       - master
     paths:
-      - 'src/**'
-      - 'spi/**'
-      - 'scripts/**'
-      - 'overrides/**'
-      - 'mkdocs.yml'
-  workflow_dispatch:  # 允许手动触发
+      - "src/**"
+      - "spi/**"
+      - "scripts/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+
+  workflow_dispatch:
 
 permissions:
   contents: write
 
 jobs:
-  build:
-    name: Build Documentation
+  documentation:
+    name: Build and Deploy Documentation
     runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Cache pip dependencies
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
-      - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y pngquant
 
-      - name: Install dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r requirements.txt
-
-      - name: Build documentation
-        run: mkdocs build
-
-  deploy:
-    name: Deploy to GitHub Pages
-    runs-on: ubuntu-latest
-    needs: build
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
-          fetch-depth: 0  # 获取完整历史
+          fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
-          python-version: '3.11'
+          python-version: "3.12"
 
-      - name: Cache pip dependencies
-        uses: actions/cache@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+          version: "latest"
+          enable-cache: true
 
       - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y pngquant
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pngquant
 
       - name: Install dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r requirements.txt
+        run: uv sync
 
-      - name: Configure Git
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Build documentation
+        run: uv run mkdocs build
 
       - name: Deploy to GitHub Pages
-        run: mkdocs gh-deploy --force
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        run: uv run mkdocs gh-deploy --force
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -4,4 +4,6 @@ __pycache__
 site/
 tmp/
 .cache/
-.obsidian/
+.obsidian/
+.venv/
+*.lock

Makefile

@@ -16,13 +16,18 @@ help:
 
 # Install dependencies
 install:
-	@echo "正在安装文档依赖..."
-	pip install -r requirements.txt
+	@if command -v uv >/dev/null 2>&1; then \
+		echo "检测到 uv，使用 uv 安装依赖..."; \
+		uv sync; \
+	else \
+		echo "未检测到 uv，使用 pip 安装依赖..."; \
+		python -m pip install -e .; \
+	fi
 
 # Generate SPI registry page
 spi:
 	@echo "正在生成 SPI 已收录产品页面..."
-	python3 scripts/generate_spi_registry.py
+	python scripts/generate_spi_registry.py
 
 # Live preview server
 serve:

README.md

@@ -8,10 +8,10 @@
 
 ```bash
 # 使用 pip
-pip install mkdocs mkdocs-material mkdocs-material-extensions jieba
+pip install -e .
 
 # 或使用 uv
-uv pip install -r pyproject.toml
+uv sync && source .venv/bin/activate
 ```
 
 ### 本地预览
@@ -58,7 +58,7 @@ mkdocs gh-deploy --force
 
 ## 目录结构
 
-```
+```bash
 superpod-whitepaper/
 ├── mkdocs.yml          # MkDocs 配置文件
 ├── pyproject.toml      # Python 项目配置

mkdocs.yml

@@ -122,75 +122,75 @@ markdown_extensions:
 
 nav:
   - 首页: index.md
-  - 前言: 
-    - 00-preface.md
-    - 编写委员会: 00-editorial-board.md
+  - 前言:
+      - 00-preface.md
+      - 编写委员会: 00-editorial-board.md
   - 架构分析:
-    - 01-architecture/index.md
-    - 产品实践:
-      - NVIDIA 超节点: 01-architecture/01-nvidia.md
-      - 华为超节点: 01-architecture/02-huawei.md
-    - 技术基础:
-      - 物理层与电气接口: 01-architecture/03-electrical.md
-      - 链路层与事务协议: 01-architecture/04-protocols.md
-      - 拓扑与组网: 01-architecture/05-topology.md
-    - 系统实现:
-      - 系统架构: 01-architecture/06-system-architecture.md
-      - 整机工程: 01-architecture/07-server-architecture.md
+      - 01-architecture/index.md
+      - 产品实践:
+          - NVIDIA 超节点: 01-architecture/01-nvidia.md
+          - 华为超节点: 01-architecture/02-huawei.md
+      - 技术基础:
+          - 物理层与电气接口: 01-architecture/03-electrical.md
+          - 链路层与事务协议: 01-architecture/04-protocols.md
+          - 拓扑与组网: 01-architecture/05-topology.md
+      - 系统实现:
+          - 系统架构: 01-architecture/06-system-architecture.md
+          - 整机工程: 01-architecture/07-server-architecture.md
   - 软件系统:
-    - 02-software/index.md
-    - 统一访存:
-      - 硬件内存语义: 02-software/hw-memory-foundations.md
-      - 软件访存机制: 02-software/memory-semantics.md
-      - 内存池化技术: 02-software/memory-pooling.md
-    - 编程模型:
-      - 集合通信: 02-software/ccl.md
-      - 共享内存: 02-software/shmem.md
-    - RAS体系: 
-      - 02-software/ras.md
-    - 训推系统: 
-      - 02-software/train-infer.md
+      - 02-software/index.md
+      - 统一访存:
+          - 硬件内存语义: 02-software/hw-memory-foundations.md
+          - 软件访存机制: 02-software/memory-semantics.md
+          - 内存池化技术: 02-software/memory-pooling.md
+      - 编程模型:
+          - 集合通信: 02-software/ccl.md
+          - 共享内存: 02-software/shmem.md
+      - RAS体系:
+          - 02-software/ras.md
+      - 训推系统:
+          - 02-software/train-infer.md
   - 建模仿真:
-    - 03-simulation/index.md
-    - 负载模型：定义需求侧的压力画像: 03-simulation/2.workload_modeling.md
-    - 系统模型：映射与编排的推演引擎: 03-simulation/3.system_simulation.md
-    - 校准验证与共演进闭环: 03-simulation/coevolution.md
-    - 方法论落地：异构推理架构的帕累托分析: 03-simulation/case-inference.md
+      - 03-simulation/index.md
+      - 负载模型：定义需求侧的压力画像: 03-simulation/2.workload_modeling.md
+      - 系统模型：映射与编排的推演引擎: 03-simulation/3.system_simulation.md
+      - 校准验证与共演进闭环: 03-simulation/coevolution.md
+      - 方法论落地：异构推理架构的帕累托分析: 03-simulation/case-inference.md
   - 参考设计:
-    - 04-reference-designs/index.md
-    - 标准构型：总线全对等互联方案: 04-reference-designs/standard-bus.md
-    - 标准构型：以太全对等互联方案: 04-reference-designs/standard-ether.md
-    - 探索构型：Dragonfly + OCS 方案: 04-reference-designs/dragonfly-ocs.md
-    - 探索构型：3D Torus + OCS 方案: 04-reference-designs/torus-ocs.md
-    - 探索构型：大环路 + 分布式 dOCS 方案: 04-reference-designs/ring-docs.md
+      - 04-reference-designs/index.md
+      - 标准构型：总线全对等互联方案: 04-reference-designs/standard-bus.md
+      - 标准构型：以太全对等互联方案: 04-reference-designs/standard-ether.md
+      - 探索构型：Dragonfly + OCS 方案: 04-reference-designs/dragonfly-ocs.md
+      - 探索构型：3D Torus + OCS 方案: 04-reference-designs/torus-ocs.md
+      - 探索构型：大环路 + 分布式 dOCS 方案: 04-reference-designs/ring-docs.md
   - 未来演进:
-    - 05-future/index.md
-    - 互联技术演进:
-      - 光互联与交换: 05-future/interconnect.md
-      - 先进互联拓扑演进: 05-future/topology.md
-      - Scale-Up 总线与互联语义: 05-future/bus.md
-    - 先进封装技术演进:
-      - 光电互连封装（LPO/NPO/CPO）: 05-future/packaging.md
-      - Chiplet 多Die 集成（2.5D/3D）: 05-future/chiplet.md
-      - 堆叠内存技术（HBM/3D DRAM）: 05-future/hbm.md
+      - 05-future/index.md
+      - 互联技术演进:
+          - 光互联与交换: 05-future/interconnect.md
+          - 先进互联拓扑演进: 05-future/topology.md
+          - Scale-Up 总线与互联语义: 05-future/bus.md
+      - 先进封装技术演进:
+          - 光电互连封装（LPO/NPO/CPO）: 05-future/packaging.md
+          - Chiplet 多Die 集成（2.5D/3D）: 05-future/chiplet.md
+          - 堆叠内存技术（HBM/3D DRAM）: 05-future/hbm.md
     # - 先进模型技术演进:
     #   - 模型技术演进总览: 05-future/model-tech.md
     #   - 低精度数值格式: 05-future/low-precision.md
     #   - 超长序列技术: 05-future/long-context.md
     #   - 超稀疏模型技术: 05-future/ultra-sparse.md
     #   - 多模态融合技术: 05-future/multimodal.md
   - 结语与附录:
-    - 总结: 06-conclusion.md
-    - 证据等级与判断口径: 07-evidence-grading.md
-    - 附录: 07-appendix.md
+      - 总结: 06-conclusion.md
+      - 证据等级与判断口径: 07-evidence-grading.md
+      - 附录: 07-appendix.md
   - 版本历史: 00-version-history.md
   - 参与方式:
-    - 如何参与: contributing.md
-    - 为何参与: contributing/industry-participation.md
+      - 如何参与: contributing.md
+      - 为何参与: contributing/industry-participation.md
   - 产业协同与 SPI 筹备:
-    - SuperPod Pareto Index (SPI) 筹备说明书: 07-spi.md
-    - SPI 现有收录产品名录: 07-spi-registry.md
-    - 产业生态地图: 08-ecosystem-map.md
+      - SuperPod Pareto Index (SPI) 筹备说明书: 07-spi.md
+      - SPI 现有收录产品名录: 07-spi-registry.md
+      - 产业生态地图: 08-ecosystem-map.md
 
 extra:
   analytics:
@@ -294,4 +294,3 @@ extra_javascript:
   - javascripts/evidence-tags.js
 
 copyright: © 2026 DeepLink 团队. 保留所有权利.
-

pyproject.toml

@@ -5,17 +5,19 @@ description = "SuperPod 技术白皮书 - 分布式 AI 推理加速架构"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "mkdocs>=1.6.0",
-    "mkdocs-material>=9.5.0",
-    "mkdocs-material-extensions>=1.3.0",
-    "mkdocs-encryptcontent-plugin>=3.1.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.7",
+    "mkdocs-material-extensions>=1.3.1",
+    "mkdocs-charts-plugin",
     "mkdocs-excalidraw",
     "mkdocs-heti-plugin",
-    "jieba>=0.42.1",
-    "mkdocs-git-revision-date-localized-plugin>=1.5.1",
-    "mkdocs-glightbox>=0.4.0",
-    "mkdocs-minify-plugin>=0.8.0",
-    "pillow>=10.0",
-    "cairosvg>=2.7",
+    "mkdocs-encryptcontent-plugin>=3.1.0",              # 内容加密
+    "jieba>=0.42.1",                                    # 中文搜索支持
+    "pyyaml>=6.0.3",
+    "pygments==2.20.0",
+    "mkdocs-git-revision-date-localized-plugin>=1.5.3", # SEO & 站点增强
+    "mkdocs-glightbox>=0.5.2",                          # 图片灯箱
+    "mkdocs-minify-plugin>=0.8.0",                      # 构建优化
+    "pillow>=12.3.0",
+    "cairosvg>=2.9.0",
 ]
-

src/07-spi-registry.md

@@ -7,7 +7,7 @@ keywords: "SPI,产品名录,SuperPod Pareto Index,超节点,产品登记,互联,
 
 <!-- This file is auto-generated by scripts/generate_spi_registry.py. Do not edit directly. -->
 
-本页由构建脚本自动扫描 `spi/products/` 目录生成。生成日期：2026-03-31。
+本页由构建脚本自动扫描 `spi/products/` 目录生成。生成日期：2026-08-10。
 
 当前仓库共收录 **1** 个产品条目。