| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 13 天前 | ||
| 20 天前 | ||
| 29 天前 | ||
| 29 天前 | ||
| 20 天前 | ||
| 13 天前 | ||
| 20 天前 | ||
| 20 天前 | ||
| 20 天前 |
文档构建与发布
本地 Linux 构建
准备 Python 环境并安装依赖后执行：
SANPO_DOCS_PYTHON=.venv/bin/python \
SANPO_DOCS_V3_SOURCE=/path/to/current/v3 \
SANPO_DOCS_V4_SOURCE=/path/to/current/v4 \
SANPO_DOCS_V6_SOURCE=/path/to/current/v6 \
bash scripts/docs/build-docs.sh /tmp/sanpo-docs-site
日常构建只重新构建当前版本 V8 的中英文文档。V3、V4 和 V6 从当前线上目录继承，正文和静态资源不重建；构建脚本只统一四个版本的版本选择器，并逐文件验证冻结版本没有发生其他变化。构建完成后会检查 V8 源文档链接和生成页面的本地链接。
文档站首页只包含两个产品类别：
- 通信集成板：
SPINE V8（当前）、SPINE V6（维护）、SPINE V4（维护）、SPINE V3（历史）。 - 关节电机：产品文档准备完成后再增加具体系列入口。
软件、工具和样例不设为首页独立类别，统一放在对应产品版本的说明文档内。
服务器发布
Windows 一键发布
在 PowerShell 中进入 gitcode_unified_main，一条命令完成提交、推送
unified-main、服务器安全快进 main、构建和发布：
.\scripts\docs\release-docs.ps1 `
-All `
-CommitMessage "docs: update documentation"
脚本会先列出全部改动，并要求输入大写 RELEASE 后才会暂存。-All 表示
提交当前仓库的所有改动；如果只发布指定文件，应使用：
.\scripts\docs\release-docs.ps1 `
-Paths README.md,products/spine/v8/docs/zh/get_started.md `
-CommitMessage "docs: update V8 guide"
需要指定 SSH 私钥时增加：
-SshKeyPath "$env:USERPROFILE\.ssh\sanpo_docs_ed25519"
脚本会优先自动查找上述长期密钥路径，并兼容当前临时发布密钥。也可以通过
-KnownHostsPath 指定独立的 known_hosts 文件。
可先运行 -All -DryRun 检查范围。自动化环境可以加 -Yes 跳过
RELEASE 确认，但日常人工发布不建议跳过。脚本只发布本仓库和文档站，
不会部署 website_v8。
日常发布只需一个命令：
sanpo-docs-release
该命令先把远端 unified-main 安全快进同步到 main，然后构建并发布生产站点。不会使用强制推送；如果两个分支已经分叉，命令会停止，不会覆盖任何提交。
日常发布会冻结 V3/V4/V6 正文，只重新构建 V8。
本地完成修改后，只需先推送 unified-main：
git push origin unified-main
然后登录服务器执行 sanpo-docs-release 即可。
受控更新 V4
只有明确修改 V4 文档时，才使用：
sanpo-docs-release --update-v4
该模式会从 products/spine/v4/f407/docs 重新构建 V4 中英文，检查 V4 源文档中的本地链接和 GitCode main 路径，再检查生成站点。发布成功后，新 V4 会成为以后日常发布的冻结基线。
受控更新 V6
只有明确修改 V6 文档时，才使用：
sanpo-docs-release --update-v6
V4 和 V6 都需要受控更新时可同时传入两个选项。V3 只有静态历史站点，不通过当前源码重建。
仅重新构建并发布当前 main（不同步分支）：
sanpo-docs-publish
构建 unified-main 预览而不影响生产站点：
sanpo-docs-publish unified-main
服务器发布脚本通过临时 Git worktree 构建指定远端分支。新版本构建和检查全部成功后，才会原子切换 current 或 preview-current 符号链接。如果构建失败，线上站点保持旧版本；修复后重新执行 sanpo-docs-release 即可。
正式发布顺序
- 在
unified-main完成 V8 文档、样例和固件校验并提交。 - 发布
unified-main到preview-current，检查 V8 中英文、旧版本导航和首页。 - 将验证过的提交快进到
main，创建产品发布标签后推送。 - 发布
main，原子切换current；验证线上后保留上一个 release 目录作为回滚点。 website_v8使用独立发布流程，网站未完成时不得随文档发布。