diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 3197aee..75d8f0f 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.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 diff --git a/.github/workflows/pr-preview.yml b/.github/workflows/pr-preview.yml new file mode 100644 index 0000000..8002012 --- /dev/null +++ b/.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 + }); diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 40b7fb4..b683b23 100644 --- a/DEPLOYMENT.md +++ b/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. **本地测试** diff --git a/docs/build/html/.doctrees/environment.pickle b/docs/build/html/.doctrees/environment.pickle index 04932ef..3783875 100644 Binary files a/docs/build/html/.doctrees/environment.pickle and b/docs/build/html/.doctrees/environment.pickle differ diff --git a/docs/build/html/en/.doctrees/environment.pickle b/docs/build/html/en/.doctrees/environment.pickle index 391b8d8..c26637e 100644 Binary files a/docs/build/html/en/.doctrees/environment.pickle and b/docs/build/html/en/.doctrees/environment.pickle differ diff --git a/docs/build/locale/.doctrees/environment.pickle b/docs/build/locale/.doctrees/environment.pickle index ed0cde3..0df5a08 100644 Binary files a/docs/build/locale/.doctrees/environment.pickle and b/docs/build/locale/.doctrees/environment.pickle differ diff --git a/docs/build/locale/.doctrees/getting_started/index.doctree b/docs/build/locale/.doctrees/getting_started/index.doctree index d0aa856..547c91e 100644 Binary files a/docs/build/locale/.doctrees/getting_started/index.doctree and b/docs/build/locale/.doctrees/getting_started/index.doctree differ diff --git a/docs/requirements.txt b/docs/requirements.txt index a303515..123795a 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/source/_static/favicon.svg b/docs/source/_static/favicon.svg new file mode 100644 index 0000000..609e33d --- /dev/null +++ b/docs/source/_static/favicon.svg @@ -0,0 +1,10 @@ + + + + + + + + + X +