ci: 优化文档部署工作流并更新 GitHub Actions 版本

.github/workflows/deploy-docs.yml

@@ -1,4 +1,4 @@
-name: Deploy Documentation to GitHub Pages
+name: Build and Deploy Documentation
 
 on:
   push:
@@ -25,9 +25,17 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.9'
+        python-version: '3.11'
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
 
     - name: Install dependencies
       run: |
@@ -39,23 +47,34 @@ jobs:
         cd docs
         python build_multilang.py
 
+    - name: Upload build artifacts (for PR preview)
+      uses: actions/upload-artifact@v4
+      if: github.event_name == 'pull_request'
+      with:
+        name: documentation-preview
+        path: docs/build/html
+        retention-days: 7
+
     - name: Setup Pages
-      uses: actions/configure-pages@v3
+      uses: actions/configure-pages@v4
+      if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
 
-    - name: Upload artifact
-      uses: actions/upload-pages-artifact@v2
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
       with:
         path: docs/build/html
-        
+
   deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
 
     steps:
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4

.github/workflows/pr-preview.yml

@@ -0,0 +1,59 @@
+name: PR Preview Comment
+
+on:
+  workflow_run:
+    workflows: ["Build and Deploy Documentation"]
+    types:
+      - completed
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+
+    steps:
+    - name: Comment on PR
+      uses: actions/github-script@v7
+      with:
+        script: |
+          // Get PR number from the workflow run
+          const pullRequests = context.payload.workflow_run.pull_requests;
+          if (!pullRequests || pullRequests.length === 0) {
+            console.log('No pull requests found for this workflow run');
+            return;
+          }
+
+          const prNumber = pullRequests[0].number;
+          const runId = context.payload.workflow_run.id;
+          const repoOwner = context.repo.owner;
+          const repoName = context.repo.repo;
+
+          const comment = `## 📚 Documentation Preview
+
+          ✅ **Build Status**: Success
+          🔗 **Artifacts**: [Download documentation preview](https://github.com/${repoOwner}/${repoName}/actions/runs/${runId})
+
+          ### 📋 Build Summary
+          - **Multi-language build**: Completed
+          - **Chinese docs**: Generated
+          - **English docs**: Generated
+          - **Build artifacts**: Available for 7 days
+
+          ### 🚀 Next Steps
+          After merging this PR, the documentation will be automatically deployed to:
+          - **Chinese**: https://${repoOwner}.github.io/${repoName}/
+          - **English**: https://${repoOwner}.github.io/${repoName}/en/
+
+          ---
+          *This comment was automatically generated by GitHub Actions*`;
+
+          await github.rest.issues.createComment({
+            issue_number: prNumber,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: comment
+          });

DEPLOYMENT.md

@@ -17,11 +17,20 @@
 
 ### 部署流程
 
-当你推送代码到 `main` 或 `master` 分支时，GitHub Actions 会自动：
+#### PR 构建验证
+当你创建或更新 Pull Request 时，GitHub Actions 会自动：
 
 1. **安装依赖**: 安装 Python 和 Sphinx 相关包
 2. **构建文档**: 运行 `build_multilang.py` 生成多语言文档
-3. **部署到 Pages**: 将构建结果发布到 GitHub Pages
+3. **上传预览**: 将构建结果作为 artifacts 上传（保留7天）
+4. **状态检查**: 在PR中显示构建状态和预览链接
+
+#### 生产部署
+当你推送代码到 `main` 或 `master` 分支时，GitHub Actions 会自动：
+
+1. **构建文档**: 执行完整的多语言构建
+2. **部署到 Pages**: 将构建结果发布到 GitHub Pages
+3. **更新网站**: 实时更新在线文档
 
 ### 访问地址
 
@@ -86,6 +95,7 @@ enterprise-docs/
 1. **构建失败**
    - 检查 `requirements.txt` 中的依赖版本
    - 查看 GitHub Actions 日志中的错误信息
+   - 确认使用的是最新版本的 GitHub Actions
 
 2. **页面显示异常**
    - 确保 `.nojekyll` 文件存在于输出目录
@@ -95,6 +105,13 @@ enterprise-docs/
    - 确认 `switcher.json` 文件已正确生成
    - 检查语言切换器配置
 
+4. **GitHub Actions 版本错误**
+   - 如果遇到 "deprecated version" 错误，确保使用最新版本：
+     - `actions/setup-python@v5`
+     - `actions/configure-pages@v4`
+     - `actions/upload-pages-artifact@v3`
+     - `actions/deploy-pages@v4`
+
 ### 调试步骤
 
 1. **本地测试**

docs/requirements.txt

@@ -1,4 +1,8 @@
-sphinx>=7.0.0
-sphinx-rtd-theme>=1.3.0
+sphinx>=7.0.0,<8.0.0
+sphinx-rtd-theme>=2.0.0
 sphinx-intl>=2.1.0
 sphinx-autosummary-accessors>=2023.4.0
+sphinx-tabs>=3.4.0
+sphinx-design>=0.5.0
+ipython>=8.0.0
+pydata-sphinx-theme>=0.15.0