feat: online docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,98 @@
+name: 构建和部署文档
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: '要部署文档的分支'
+        required: false
+        default: 'main'
+        type: string
+      deploy_to_pages:
+        description: '是否部署到 GitHub Pages'
+        required: false
+        default: true
+        type: boolean
+
+# 设置 GITHUB_TOKEN 权限以部署到 GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 只允许一个并发部署，跳过正在进行和最新排队之间的运行
+# 但是不取消正在进行的运行，因为我们希望允许这些生产部署完成
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  # 构建文档
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.branch || github.ref }}
+
+      - name: 设置 Python 环境
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: 安装系统依赖
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+
+      - name: 安装 Python 依赖
+        run: |
+          python -m pip install --upgrade pip
+          # 以开发模式安装包以获取版本信息
+          pip install -e .
+          # 安装文档构建依赖
+          pip install -r docs/requirements.txt
+
+      - name: 配置 Pages
+        id: pages
+        uses: actions/configure-pages@v4
+        if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+
+      - name: 构建 Sphinx 文档
+        run: |
+          cd docs
+          # 清理之前的构建
+          rm -rf _build
+          # 构建 HTML 文档
+          python -m sphinx -b html . _build/html -v
+
+      - name: 检查构建结果
+        run: |
+          echo "文档构建完成，检查输出目录："
+          ls -la docs/_build/html/
+          echo "检查是否有 index.html："
+          test -f docs/_build/html/index.html && echo "✓ index.html 存在" || echo "✗ index.html 不存在"
+
+      - name: 上传构建产物
+        uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+        with:
+          path: docs/_build/html
+
+  # 部署到 GitHub Pages
+  deploy:
+    if: github.ref == 'refs/heads/main' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_to_pages == 'true')
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: 部署到 GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4