cheng874 · cheng874 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,11 +1,15 @@
 name: Deploy Docs Preview
 
 on:
-  # 当推送到 main 分支时自动触发
+  # 推送到 fork 的任意分支时触发（自动检测改动的子项目）
   push:
-    branches: ["main"]
-  # 允许手动触发工作流
+  # 允许手动触发，并可指定要预览的子项目
   workflow_dispatch:
+    inputs:
+      projects:
+        description: "要构建预览的子项目（空格分隔，如：flaggems_en flagcx_en）"
+        required: false
+        default: "flaggems_en"
 
 # 设置 GITHUB_TOKEN 的权限，允许写入 GitHub Pages
 permissions:
@@ -27,6 +31,9 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          # 需要前一次提交以便 git diff 检测改动的子项目
+          fetch-depth: 2
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -38,9 +45,105 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
 
-      - name: Build documentation
+      - name: Determine which subprojects to build
+        id: select
         run: |
-          sphinx-build -b html docs docs/_build/html
+          set -euo pipefail
+
+          # conf.py 中定义的全部子项目（作为白名单，避免构建无效目录）
+          mapfile -t ALL < <(python - <<'PY'
+          import ast, pathlib
+          src = pathlib.Path("docs/conf.py").read_text(encoding="utf-8")
+          tree = ast.parse(src)
+          for node in ast.walk(tree):
+              if isinstance(node, ast.Assign):
+                  for t in node.targets:
+                      if isinstance(t, ast.Name) and t.id == "multiproject_projects":
+                          for k in node.value.keys:
+                              print(k.value)
+          PY
+          )
+
+          declare -A VALID=()
+          for p in "${ALL[@]}"; do VALID["$p"]=1; done
+
+          SELECTED=""
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            # 手动指定
+            for p in ${{ github.event.inputs.projects }}; do
+              if [ -n "${VALID[$p]:-}" ]; then SELECTED="$SELECTED $p"; fi
+            done
+          else
+            # push：从 git diff 中提取改动的顶层子项目目录
+            BEFORE="${{ github.event.before }}"
+            if [ -z "$BEFORE" ] || ! git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
+              BEFORE="HEAD~1"
+            fi
+            CHANGED=$(git diff --name-only "$BEFORE" "${{ github.sha }}" -- 'docs/*' || true)
+            declare -A SEEN=()
+            while IFS= read -r f; do
+              # docs/<project>/...
+              proj=$(echo "$f" | sed -n 's#^docs/\([^/]*\)/.*#\1#p')
+              if [ -n "$proj" ] && [ -n "${VALID[$proj]:-}" ] && [ -z "${SEEN[$proj]:-}" ]; then
+                SEEN[$proj]=1
+                SELECTED="$SELECTED $proj"
+              fi
+            done <<< "$CHANGED"
+          fi
+
+          # 回退：未检测到改动的子项目时构建首页
+          SELECTED=$(echo "$SELECTED" | xargs || true)
+          if [ -z "$SELECTED" ]; then SELECTED="flagos_homepage"; fi
+
+          echo "Selected subprojects: $SELECTED"
+          echo "projects=$SELECTED" >> "$GITHUB_OUTPUT"
+
+      - name: Build selected subprojects
+        run: |
+          set -uo pipefail
+          OUT="docs/_build/html"
+          rm -rf "$OUT"
+          mkdir -p "$OUT"
+
+          OK=""
+          FAIL=""
+          for p in ${{ steps.select.outputs.projects }}; do
+            echo "::group::Building $p"
+            if PROJECT="$p" sphinx-build -b html docs "$OUT/$p"; then
+              OK="$OK $p"
+            else
+              FAIL="$FAIL $p"
+              echo "::warning::Build failed for subproject: $p"
+            fi
+            echo "::endgroup::"
+          done
+
+          # 生成预览着陆页
+          {
+            echo '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+            echo '<title>Docs Preview</title>'
+            echo '<style>body{font-family:sans-serif;max-width:640px;margin:3rem auto;padding:0 1rem}li{margin:.4rem 0}</style>'
+            echo '</head><body><h1>FlagOS Docs Preview</h1>'
+            echo '<p>本页仅包含本次改动构建的子项目预览。</p><ul>'
+            for p in $OK; do
+              echo "<li><a href=\"./$p/index.html\">$p</a></li>"
+            done
+            echo '</ul>'
+            if [ -n "$FAIL" ]; then
+              echo "<h2>构建失败</h2><ul>"
+              for p in $FAIL; do echo "<li>$p</li>"; done
+              echo "</ul>"
+            fi
+            echo '</body></html>'
+          } > "$OUT/index.html"
+
+          echo "Built:$OK"
+          echo "Failed:$FAIL"
+          # 全部失败才让任务失败
+          if [ -z "$OK" ]; then
+            echo "::error::No subproject built successfully."
+            exit 1
+          fi
 
       - name: Setup Pages
         uses: actions/configure-pages@v4
@@ -52,4 +155,4 @@ jobs:
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4
diff --git a/docs/flaggems_vllm_en/overview/overview.md b/docs/flaggems_vllm_en/overview/overview.md
@@ -6,8 +6,7 @@ FlagGems-vLLM is a high-performance deep learning operator library implemented u
 
 By integrating with vLLM, FlagGems-vLLM accelerates inference workloads through optimized Triton kernels that replace default operator implementations, delivering significant performance gains across diverse hardware platforms.
 
-```{toctree}
-
+```{toctre
 features.md
 
 ```
diff --git a/requirements.txt b/requirements.txt
@@ -1,13 +1,21 @@
-modelscope>=1.11.0
-sphinx
-sphinx-rtd-theme
+# GitHub Pages 预览构建用依赖，与 docs/requirements.txt 对齐（RTD 用后者）。
+# 额外加 matplotlib 以生成 opengraph social cards（消除构建警告）。
+sphinx==8.2.3
+myst-parser
+sphinx-multiproject==1.0.0
 pydata-sphinx-theme
-sphinx-book-theme
-sphinx-multiproject
-sphinx-tabs
-sphinx-prompt
+sphinx-rtd-theme
+sphinx-book-theme~=1.1
+sunpy-sphinx-theme
+sphinx-autodoc2~=0.5.0
 sphinx-design
-sphinxext-opengraph
-sphinx-tippy
-myst-parser
-sphinx-copybutton
+sphinx-copybutton
+sphinxext.rediraffe~=0.3.0
+sphinxcontrib.mermaid~=0.7.1
+sphinxext.opengraph~=0.13.0
+sphinx-pyscript
+sphinx-tippy>=0.4.3
+sphinx-togglebutton
+sphinx-tabs==3.4.7
+sphinx-prompt==1.10.2
+matplotlib