跳转至

文档维护与发布

1. 维护与发布的关系

Android 工程中的 docs/voice-assistant-site/ 是维护源；独立公开仓库 nash-nie/jdo-voice-assistant-doc 是发布镜像。接口变化时先在工程内核对代码并更新文档，再同步镜像。

flowchart LR
    Source[工程内站点源码] --> Check[严格构建与内容检查]
    Check --> Export[白名单导出]
    Export --> Repo[独立文档仓库]
    Repo -->|main 更新| Pages[Cloudflare Pages]
    Pages --> Verify[线上路径与交互验证]
文件 用途
content/ 公开页面和静态资源
mkdocs.yml 站点信息、主题、导航、搜索和扩展
requirements.txt 固定版本的构建依赖
.python-version Cloudflare 构建使用的 Python 系列
scripts/export_site.py 显式导出可公开站点内容
site/ 构建输出，忽略入库

2. 本地编辑与预览

首次在 Android 工程运行：

cd docs/voice-assistant-site
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

打开终端显示的地址，Markdown 保存后预览自动刷新。独立文档仓库从仓库根目录执行同样命令，省略第一行 cd。

页面之间用 Markdown 相对路径，例如 [Omni 接入](omni-integration.md)，构建时自动转换为网站路径。Android 源码路径仅作为文本定位依据，不建立公开站点无法访问的相对链接。

3. 页面维护规范

  1. 从当前代码确认适用 flavor、入口、参数、返回值与失败行为。
  2. 在 content/ 更新页面，技术页包含流程、关键接口和必要的 Mermaid 图。
  3. 在 mkdocs.yml 导航中加入页面，并更新关联入口。
  4. 区分实际实现、Stub、历史方案和设备待验证事项。
  5. 示例中的用户、订单、地址和凭据统一匿名化；第三方协议链接官方来源。

核对当前配置

当前 Omni 端口为 50056，旧文档写过 50055。更新文档时应追踪常量与注入配置，不能只复制旧说明。

4. 严格构建与同步

mkdocs build --strict

严格模式下导航与链接警告会中止构建。先修复，再导出；不要取消严格模式来放过损坏链接。

在 Android 工程根目录执行：

DOCS_EXPORT_DIR="$(mktemp -d /tmp/jdo-voice-doc-export.XXXXXX)"
python3 docs/voice-assistant-site/scripts/export_site.py "$DOCS_EXPORT_DIR"

脚本只复制配置、依赖、README、导出脚本和允许类型的公开内容文件。它显示导出与跳过数量，拒绝非空目标、源目录重叠和符号链接，不执行删除或 Git 发布。

将导出目录与独立文档仓库工作区进行差异审查，确认只包含本次公开内容后提交 PR。文档仓库的 main 更新触发生产构建。删页或改名需要显式处理旧文件，避免旧内容继续出现在搜索中。

5. Cloudflare Pages 设置

进入 Workers & Pages，创建 Pages 项目并连接 GitHub。选择 Git 接入；仅上传静态文件的项目不能沿用此处的 Git 自动部署流程。

设置 值
GitHub 仓库 nash-nie/jdo-voice-assistant-doc
项目名 jdo-voice-assistant-doc
生产分支 main
框架预设 None
构建根目录 仓库根目录，留空
构建命令 pip install -r requirements.txt && mkdocs build --strict
构建输出目录 site
Python 版本 .python-version 指定 3.11

首次保存后查看依赖安装、MkDocs 构建和静态资源上传日志。项目域名为 https://jdo-voice-assistant-doc.pages.dev/。

站点不需要 Android SDK、Gradle、业务后端连接或应用凭据。搜索在浏览器端运行；Mermaid 由主题按需加载渲染，首次打开图表需要能访问其脚本资源。

6. 发布验收

检查 通过标准
构建 Pages 对应 Git 提交的构建成功
首页 正式域名 HTTPS 可访问，导航与资源正常
深层链接 /omni-integration/ 等路径直接访问、刷新均正常
搜索 输入“唤醒”“支付”能查到相关内容
图表 显示为图形，无语法错误
代码复制 复制按钮可用，复制内容与示例一致
主题与移动端 深浅模式可切换，窄屏导航可展开
公开内容 页面、源码及搜索索引无真实凭据或个人资料

记录部署 ID、Git 提交、验证时间和问题结果。工程内日志与截图放在既有 tasks/verification/，不导出到公开仓库。

7. 失败处理与回退

  • 仓库不可选：检查 Cloudflare 的 GitHub 安装是否有该文档仓库权限，仅增加所需仓库。
  • 依赖安装失败：检查 Python 版本及 pip 错误，用相同版本本地复现。
  • 严格构建失败：修复链接、导航或扩展配置，重新更新提交。
  • 构建成功但页面缺失：确认输出目录为 site，根目录为文档仓库根目录。
  • 生产内容有问题：在 Pages 部署历史中回退到已验证生产部署，同时在维护源修复并发布新提交，避免下次自动部署覆盖回退结果。
  • 图表未显示：检查浏览器网络与控制台，区分脚本加载失败和 Mermaid 语法错误。

回退后重新检查首页、深层路径和搜索。静态站点构建成功不代表 Android 功能已经完成实车验收。