docs: enable versioned docs publishing (#103)

.github/workflows/docs-pages.yml

@@ -4,26 +4,43 @@ on:
   push:
     branches: ["main"]
   workflow_dispatch:
+    inputs:
+      version:
+        description: Docs version path to deploy, for example latest or v0.1.0
+        required: false
+        default: latest
+      aliases:
+        description: Optional space-separated aliases for this docs version
+        required: false
+        default: ""
+      default_version:
+        description: Version or alias that the docs root should redirect to
+        required: false
+        default: latest
 
 permissions:
-  contents: read
+  contents: write
   pages: write
   id-token: write
 
+env:
+  DOCS_VERSION: ${{ github.event.inputs.version || 'latest' }}
+  DOCS_ALIASES: ${{ github.event.inputs.aliases || '' }}
+  DOCS_DEFAULT_VERSION: ${{ github.event.inputs.default_version || 'latest' }}
+
 concurrency:
   group: docs-pages
   cancel-in-progress: true
 
 jobs:
-  deploy:
-    if: github.repository == 'datascale-ai/opentalking' && github.ref == 'refs/heads/main'
+  build-versioned-docs:
+    if: github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
 
     steps:
       - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v6
         with:
@@ -36,16 +53,51 @@ jobs:
           pip install -r docs/requirements.txt
 
       - name: Configure Pages
+        if: ${{ github.event.repository.has_pages }}
         uses: actions/configure-pages@v6
 
       - name: Build Docs
         run: python -m mkdocs build --strict --clean
 
+      - name: Configure versioned docs git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy versioned docs to gh-pages
+        run: |
+          git fetch origin gh-pages --depth=1 || true
+          read -r -a aliases <<< "${DOCS_ALIASES}"
+          title_args=()
+          if [ "${DOCS_VERSION}" = "latest" ]; then
+            title_args=(--title Latest)
+          fi
+          mike deploy --push --allow-empty --update-aliases --alias-type=redirect "${title_args[@]}" "${DOCS_VERSION}" "${aliases[@]}"
+          mike set-default --push --allow-empty "${DOCS_DEFAULT_VERSION}"
+
+      - name: Export versioned docs artifact
+        if: ${{ github.repository == 'datascale-ai/opentalking' && github.event.repository.has_pages }}
+        run: |
+          rm -rf site /tmp/opentalking-gh-pages
+          git worktree add /tmp/opentalking-gh-pages gh-pages
+          rsync -a --delete --exclude .git /tmp/opentalking-gh-pages/ site/
+          git worktree remove /tmp/opentalking-gh-pages
+
       - name: Upload Pages Artifact
+        if: ${{ github.repository == 'datascale-ai/opentalking' && github.event.repository.has_pages }}
         uses: actions/upload-pages-artifact@v5
         with:
           path: site
 
+  deploy-pages:
+    needs: build-versioned-docs
+    if: ${{ github.repository == 'datascale-ai/opentalking' && github.event.repository.has_pages }}
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5

docs/en/community/publishing-docs.md

@@ -0,0 +1,27 @@
+# Docs Publishing
+
+OpenTalking builds its documentation with MkDocs and Material for MkDocs, and uses `mike` to maintain versioned documentation directories.
+
+## Local Validation
+
+Install the documentation dependencies:
+
+```bash
+python -m pip install -r docs/requirements.txt
+```
+
+Build with the same strict mode used by CI:
+
+```bash
+python -m mkdocs build --strict --clean
+```
+
+## Versioned Publishing
+
+A push to `main` publishes one entry by default:
+
+- `/latest/`: the current main-branch documentation and the default site entry
+
+For a formal release, start `.github/workflows/docs-pages.yml` manually from the matching release branch or tag and set `version` to the release number, for example `v0.1.0`. Formal releases are kept under frozen paths such as `/v0.1.0/` and are not overwritten by later main-branch docs. To make a version the default landing point, set `default_version` to that version or `latest`.
+
+The workflow first writes the versioned site content to the `gh-pages` branch. If GitHub Pages is not enabled yet, it still maintains `gh-pages`, but skips the Pages artifact and deploy steps. When enabling Pages, choose GitHub Actions as the source.

docs/en/model-deployment/index.md

@@ -64,3 +64,7 @@ bash scripts/quickstart/start_frontend.sh --api-port 8000 --web-port 5173 --host
 ```
 
 For a remote server, forward your local browser port to the server `5173`, then open `http://127.0.0.1:5173`.
+
+## Documentation Versions
+
+The published site uses versioned docs: `/latest/` points at the current main docs, and formal releases are kept under frozen paths such as `/vX.Y.Z/`. For production deployments, prefer the docs version that matches the Python package, GitHub Release, or Docker image tag you installed.

docs/requirements.txt

@@ -2,3 +2,4 @@ mkdocs==1.6.*
 mkdocs-material==9.5.*
 mkdocs-static-i18n==1.2.*
 pymdown-extensions==10.*
+mike==2.*

docs/zh/community/publishing-docs.md

@@ -0,0 +1,27 @@
+# 文档发布
+
+OpenTalking 使用 MkDocs 和 Material for MkDocs 构建文档站，并用 `mike` 维护版本化发布目录。
+
+## 本地验证
+
+安装文档依赖：
+
+```bash
+python -m pip install -r docs/requirements.txt
+```
+
+按 CI 口径构建：
+
+```bash
+python -m mkdocs build --strict --clean
+```
+
+## 版本化发布
+
+`main` 分支 push 会默认发布一个入口：
+
+- `/latest/`：当前 main 分支文档，也是站点默认入口
+
+正式版本发布时，从对应 release 分支或 tag 手动触发 `.github/workflows/docs-pages.yml`，把 `version` 设为发布号，例如 `v0.1.0`。正式版本会保留在 `/v0.1.0/` 这样的冻结路径下，不会被后续 main 文档覆盖。如果希望站点根路径默认进入某个版本，把 `default_version` 设为对应版本或 `latest`。
+
+workflow 会先把版本化站点内容写入 `gh-pages` 分支。如果仓库尚未启用 GitHub Pages，它仍会维护 `gh-pages` 内容，但会跳过 Pages artifact 和 deploy 步骤。启用 Pages 时，source 选择 GitHub Actions。

docs/zh/model-deployment/index.md

@@ -63,3 +63,7 @@ bash scripts/quickstart/start_frontend.sh --api-port 8000 --web-port 5173 --host
 ```
 
 远程服务器部署时，把本地浏览器端口映射到服务器 `5173`，再打开 `http://127.0.0.1:5173`。
+
+## 文档版本
+
+线上文档使用版本化发布：`/latest/` 指向当前 main 文档，正式版本会保留在 `/vX.Y.Z/` 这样的冻结路径下。部署生产环境时，优先查看与你安装的 Python 包、GitHub Release 或 Docker 镜像 tag 对应的版本文档。

mkdocs.yml

@@ -48,6 +48,8 @@ theme:
     repo: fontawesome/brands/github
 
 extra:
+  version:
+    provider: mike
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/datascale-ai/opentalking
@@ -150,6 +152,7 @@ plugins:
             Model Adapter: 模型适配器
             Contributing: 贡献指南
             Community: 社区
+            Docs Publishing: 文档发布
             Overview: 概览
             Metrics: 指标定义
             Runbook: 运行方法
@@ -273,6 +276,7 @@ nav:
           - Support Matrix: model-deployment/support-matrix.md
       - Reference Materials:
           - Reference Materials Overview: reference/index.md
+          - Docs Publishing: community/publishing-docs.md
           - Benchmark: reference/benchmark.md
           - Changelog: reference/changelog.md
       - FAQ: