docs(pages): add user-facing OctoBus integration quick start - #651
Conversation
|
PR Title: docs(pages): add user-facing OctoBus integration q... Commit: 本次变更新增了 OctoBus 集成快速开始文档(英文 docs/pages/octobus-quickstart.md 与中文 docs/pages/zh-CN/octobus-quickstart.md,各 214 行),并在文档站点构建/校验工具中登记这两份新页面:render-pages.mjs 的 manuals 数组新增 EN/ZH 两条渲染条目(含 title、lang、alternate 互链),check-pages.mjs 的 manualNames 与 expectedOutput 同步新增源文件与输出 HTML。 审查结论:改动整体正确且自洽。构建链路方面,新增条目与 check-pages.mjs 的 checkSourceLayout(根与 zh-CN 目录 markdown 集合必须与 manualNames 完全一致)、checkOutputWhitelist(输出文件集合必须与 expectedOutput 一致)、checkInternalLinks(语言互链 alternate 可正确解析)、checkEnglishManuals(英文文档不含 CJK 字符)等校验均能通过;两页面的 alternate 链接相对路径与既有页面模式一致。文档内容方面,与 docs/design/octobus_integration.md 实现说明核对后,控制面/数据面、CAP_GRPC_LISTEN/CAP_GRPC_TARGET/CAP_TOKEN、catalog.md 注入、best-effort 语义等关键描述均一致;文档引用的仓库内文件(docs/design/octobus_integration.md、README.zh-CN.md、yaml manual 等)均存在。唯一发现是新增的 quickstart 页面没有接入 renderPage 的站点导航(navItems 为硬编码的四项),也未出现在首页中,发布后只能通过直接 URL 访问,存在可发现性缺口(低严重度)。 |
| title: "OctoBus Integration Quick Start", | ||
| lang: "en", | ||
| alternate: "zh-CN/octobus-quickstart.html", | ||
| }, |
There was a problem hiding this comment.
新增 OctoBus 快速开始页面未接入站点导航,发布后无法从文档站导航发现
本次变更把 octobus-quickstart.html 注册进渲染与白名单校验,页面会被发布;但 renderPage 的站点导航仍是硬编码的四项(Home/CLI Manual/YAML Manual/Connect Transport),未包含新增的 octobus 页面,且 docs/pages/index.html 也未在本变更中链接该页面。结果是该快速开始文档只能通过直接 URL 访问,浏览文档站的用户无法从导航发现它,削弱了 quickstart 的引导价值;这也与其它公开手册(command-line、agent-compose-yaml、connect-transport-matrix)均出现在导航中的既有模式不一致。
Problem code:
Changed code at tools/genpages/render-pages.mjs:33-39
Recommendation:
在 renderPage 的 labels 与 navItems 中加入 octobus-quickstart 导航项(EN/ZH 各一个条目),使新页面在站点头部导航中可达。注意保持 zh-CN 页面的相对 href 仍解析到 zh-CN/octobus-quickstart.html,并确认不会触发 checkNavigation 的 guest-image-abi 限制。
Suggested diff:
diff --git a/tools/genpages/render-pages.mjs b/tools/genpages/render-pages.mjs
--- a/tools/genpages/render-pages.mjs
+++ b/tools/genpages/render-pages.mjs
@@ -108,11 +108,13 @@ function renderPage(manual, body) {
const root = nested ? "../" : "./";
const labels = lang === "zh-CN"
- ? ["首页", "命令行手册", "YAML 配置手册", "Connect 传输矩阵"]
- : ["Home", "CLI Manual", "YAML Manual", "Connect Transport"];
+ ? ["首页", "命令行手册", "YAML 配置手册", "Connect 传输矩阵", "OctoBus 快速开始"]
+ : ["Home", "CLI Manual", "YAML Manual", "Connect Transport", "OctoBus Quick Start"];
const navItems = [
[root, labels[0], ""],
["command-line-manual.html", labels[1], "command-line-manual.html"],
["agent-compose-yaml-manual.html", labels[2], "agent-compose-yaml-manual.html"],
["connect-transport-matrix.html", labels[3], "connect-transport-matrix.html"],
+ ["octobus-quickstart.html", labels[4], "octobus-quickstart.html"],
];
PR: docs: add OctoBus integration quick start guide
Closes #80
Summary
Adds a user-facing OctoBus Integration Quick Start guide (English + 中文) to the
GitHub Pages documentation site, walking a new user from a local agent-compose +
OctoBus deployment all the way to a verified capability call from inside a sandbox.
The existing documentation under
docs/design/describes the internal architecture;this guide is the operational tutorial issue #80 asks for.
What the guide covers
All seven points requested in #80:
CAP_GRPC_LISTEN/CAP_GRPC_TARGETcapset_ids, incl. project-scoped servers)catalog.md)devcapset) + Step 6 (call calculator, expect42)Plus: a concepts table mapping OctoBus ↔ agent-compose terminology, the data-plane
diagram, a troubleshooting matrix for the 7 most common misconfigurations, and the
security boundary notes (token never leaves the daemon;
CAP_TOKENvs OctoBus token).Accuracy
Every command, env var, path, and behavior in the guide was verified against:
docs/design/octobus_integration.mdanddocs/design/project_octobus_servers_design.mdpkg/capabilities/gateway.go(CAP_GRPC_TARGET/CAP_TOKENinjection, guide rendering)pkg/capability/client.go(/admin/v1/*control-plane probes)pkg/agentcompose/api/capability_v2.go(status response fields)docs/pages/agent-compose-yaml-manual.md(octobus_servers,capset_idssemantics)Files changed
docs/pages/octobus-quickstart.mddocs/pages/zh-CN/octobus-quickstart.mdtools/genpages/render-pages.mjstools/genpages/check-pages.mjsmanualNames/expectedOutputwhitelists.The two script edits are required:
check-pages.mjsasserts the exact set of filesin
docs/pages/, so any new page must be whitelisted or CI fails.Testing
Result:
Pages checks passed for 69 YAML schema fields and 12 public files(was 10files before this change). This is the same command the
pages.ymlworkflow runs.Notes for reviewers
.htmltargets because the Pages link checker resolveslinks against the rendered output; links to
README/docs/design/use GitHubabsolute URLs (skipped by the checker), matching the existing convention in
guest-image-abi.md.ids, sofragment links would fail the checker's anchor validation.
Taskfile.ymldocs:build.generatesdoes not list the new HTML outputs; it alsoomits the pre-existing
connect-transport-matrix.html, so this PR leaves ituntouched to keep the change scoped. Happy to add all missing entries if preferred.