feat: 为文档部署工作流增加PR预览功能

Author: amumu96

.github/workflows/deploy-docs.yml

@@ -1,8 +1,10 @@
-name: Deploy Documentation to GitHub Pages
+name: Build and Deploy Documentation
 
 on:
   push:
     branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
   workflow_dispatch:
 
 permissions:
@@ -15,7 +17,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
 
     steps:
@@ -45,14 +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@v4
+      if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
 
     - 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 }}
+    
+    steps:
     - name: Deploy to GitHub Pages
       id: deployment
       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. **更新网站**: 实时更新在线文档
 
 ### 访问地址