ci(docs): restore auto-deploy to UniLab-doc gh-pages on push to main

.github/workflows/docs.yml

@@ -66,3 +66,62 @@ jobs:
           name: docs-html
           path: docs/sphinx/build/html
           retention-days: 7
+
+  deploy:
+    name: Deploy to UniLab-doc gh-pages
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Install system deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+              libgl1 libegl1 libosmesa6 libglfw3 \
+              ffmpeg
+
+      - name: Install UniLab (autodoc target)
+        id: install_unilab
+        continue-on-error: true
+        # Full build so api_reference autodoc renders. If the install fails
+        # we fall back to a prose-only build and still deploy.
+        run: |
+          uv sync
+          uv pip install -r docs/sphinx/requirements.txt
+
+      - name: Configure prose-only fallback
+        if: steps.install_unilab.outcome != 'success'
+        run: |
+          echo "::warning::UniLab install failed — deploying prose-only docs"
+          echo "UNILAB_DOCS_SKIP_AUTODOC=1" >> "$GITHUB_ENV"
+
+      - name: Build full HTML
+        working-directory: docs/sphinx
+        run: uv run --no-sync sphinx-build -j auto -b html -n source build/html
+
+      - name: Push to UniLab-doc gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          # SSH deploy key for unilabsim/UniLab-doc (write access required).
+          # Stored in this repo's Secrets as UNILAB_DOC_DEPLOY_KEY.
+          deploy_key: ${{ secrets.UNILAB_DOC_DEPLOY_KEY }}
+          external_repository: unilabsim/UniLab-doc
+          publish_branch: gh-pages
+          publish_dir: docs/sphinx/build/html
+          user_name: "github-actions[bot]"
+          user_email: "github-actions[bot]@users.noreply.github.com"
+          commit_message: "docs: deploy from UniLab@${{ github.sha }}"
+          full_commit_message: |
+            docs: deploy from UniLab@${{ github.sha }}
+
+            Source: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}

docs/sphinx/README.md

@@ -74,11 +74,17 @@ UNILAB_DOCS_SKIP_AUTODOC=1 uv run --no-project --with-requirements requirements.
 CI 工作流在 `.github/workflows/docs.yml`:
 
 - **PR**: prose-only HTML build,跳过 API reference,failed 阻塞 PR
-- **push to main**: prose-only HTML build,不部署
-- **手动**: `workflow_dispatch` 可在 GitHub Actions 网页端触发同一套 prose-only CI
-
-CI 明确设置 `UNILAB_DOCS_SKIP_AUTODOC=1`,不执行 `pip install -e .`,不安装 UniLab
-运行时依赖,也不跑 linkcheck。完整构建和站点发布由开发者本地完成。
+- **push to main**: prose-only build 通过后,`deploy` job 执行完整构建(安装
+  UniLab + autodoc)并通过 deploy key(`UNILAB_DOC_DEPLOY_KEY` secret)推送到
+  [`unilabsim/UniLab-doc`](https://github.com/unilabsim/UniLab-doc) 的
+  `gh-pages` 分支,GitHub Pages 自动更新站点。完整构建安装失败时降级为
+  prose-only 构建并仍然部署
+- **手动**: `workflow_dispatch` 在 `main` 上触发时走同一套构建 + 部署;
+  在其他分支触发时只做 prose-only build
+
+PR 与 push 的检查性构建明确设置 `UNILAB_DOCS_SKIP_AUTODOC=1`,不安装 UniLab
+运行时依赖,也不跑 linkcheck。下面的本地发布流程保留为 CI 部署不可用时的
+fallback。
 
 ### UniLab-doc 仓的 Pages 设置