企业官网建设流程全解析

• 开发工具
• 构建工具

本篇技术指南围绕 Buck 项目docs/目录下的官方文档工程，完整讲解其"编辑 → 本地预览 → 测试校验 → 发布 → Javadoc 集成"的全链路工作流。读者将掌握：基于 Closure Templates 编写文档源文件、用 plovr soyweb 实现实时刷新预览、按固定模板新建一篇文档文章、通过publish.sh将文档发布到 GitHub Pages（gh-pages分支），以及将 Javadoc 一并纳入发布产物的具体操作方法。

Buck 文档工程概览：Closure Templates + plovr 的技术底座

docs/目录是 Buck 官方 HTML 文档的源文件仓库，同时包含发布这些文档所需的全部脚本。文档内容不是直接以 HTML 书写，而是采用Google Closure Templates（.soy文件）编写，再经工具链渲染为 HTML。

目录按文档主题分子目录组织，每个.soy文件最终渲染为同名.html：

• docs/about/、docs/concept/：概念类文章（如overview.soy、build_file.soy）；
• docs/command/：buck各子命令文档（build、test、query等）；
• docs/rule/：各类构建规则参考（android_binary.soy、java_library.soy等）；
• docs/function/、docs/setup/、docs/skylark/、docs/static/等：分别承载函数参考、安装指南、Skylark API 与静态资源。

支撑这套工作流的关键组件如下：

buck.page：所有文档页共用的页面模板

在 docs/__common.soy 中，{template .page}定义了每个文档页的渲染入口。它接收以下参数：

• title（必填）：页面标题，会被包装为 "Buck: {title}" 并写入<title>；
• content（必填）：页面正文 HTML；
• navid：当前页面在导航中的标识（首页传'home'，其余页面传对应的文章 id）；
• subtitle（可选）：标题下的副标题；
• prettify（可选）：是否启用 google-code-prettify 代码高亮；
• description：写入og:descriptionmeta 标签的描述文本。

该模板在header部分生成完整的 HTML 骨架：favicon、static/buck.css与static/search.css样式、Open Graph meta、Algolia 文档搜索框与 Google Analytics 埋点；在footer部分调用table_of_contents.main渲染侧边导航。这意味着你编写文章时只需关注正文内容，页面框架由模板统一承担。

globals.json则为模板提供全局变量，其中最关键的是ROOT。它作为每个内部链接的前缀（注释要求值必须以/结尾），默认"/"；若要将文档托管到个人公共目录（如/~username/buck/），可修改该值。其余变量包括FB_APP_ID、GITHUB_URL、GUAVA_BASE_URL、JDK_BASE_URL与GEN_DIR。

本地编辑文档：一条命令启动实时预览服务器

编写文档采用典型的编辑 / 刷新工作流：修改.soy源文件，然后在浏览器中刷新对应页面即可看到效果。在 Buck 仓库根目录执行：

./docs/soyweb-local.sh

然后在浏览器中访问http://localhost:9811/。该编辑/刷新循环由plovr支撑——它是 Closure Templates 的构建工具，其soyweb子命令会在本地目录上提供文档渲染服务。

脚本内部发生了什么

查看 docs/soyweb-local.sh 可以发现它并非单纯启动一个静态服务器：

cd "$(git rev-parse --show-toplevel)/docs" || exit buck run //docs:generate_buckconfig_aliases exec java -jar plovr-81ed862.jar soyweb --dir . --globals globals.json $@

1. 先通过buck run //docs:generate_buckconfig_aliases运行别名生成任务（对应 docs/generate_buckconfig_aliases.py，用于同步.buckconfig相关的文档别名）；
2. 再以docs/为服务目录、globals.json为全局变量文件启动 plovr 的 soyweb。

注意cd命令会自动切换到仓库顶层再进入docs/，因此该脚本必须在 Buck 仓库根目录下运行。脚本末尾的$@支持透传额外参数给 soyweb。

Windows 用户可运行对应的 docs/soyweb-local.ps1，其等效命令为：

buck run //docs:generate_buckconfig_aliases java -jar docs\plovr-81ed862.jar soyweb --dir docs --globals docs\globals.json

生产预览与发布用服务器（端口 9814）

发布流程还需要一个"后台运行"的 soyweb 实例，由 docs/soyweb-prod.sh 提供。与开发版相比，它额外执行了ant clean（清理可能干扰构建的残留文件），然后以--port 9814启动服务器：

ant clean buck run //docs:generate_buckconfig_aliases exec java -jar plovr-81ed862.jar soyweb --port 9814 --dir . --globals globals.json

端口约定：9811 用于本地开发预览，9814 用于发布时渲染。soy2html.py正是从http://localhost:9814/抓取渲染结果的。

新建一篇文档文章的完整步骤

新建文章非常简单：在docs/对应主题子目录下创建.soy文件，并用以下模板播种内容：

{namespace buck.ADD_YOUR_PAGE_NAME} /***/ {template .soyweb} {call buck.page} {param title: 'ADD_YOUR_TITLE' /} {param content} ADD_YOUR_CONTENT_HERE {/param} {/call} {/template}

只需替换三个全大写占位符即可：

• ADD_YOUR_PAGE_NAME：该页的命名空间后缀，需保持全局唯一；
• ADD_YOUR_TITLE：页面标题；
• ADD_YOUR_CONTENT_HERE：正文 HTML 内容。

参考一个真实文章实例

仓库中的 docs/about/overview.soy 展示了更完整的写法。除了必填的title和content，还推荐提供navid与description：

{namespace buck.overview} /***/ {template .soyweb} {call buck.page} {param title: 'Key concepts' /} {param navid: 'about_overview' /} {param description} An overview of some fundamental concepts in Buck. {/param} {param content} <p>Buck has a number of fundamental concepts:</p> ... {/param} {/call} {/template}

• navid用于让页面在侧边导航（由table_of_contents.main渲染）中高亮当前所在章节；
• description会进入og:descriptionmeta 标签，影响页面被分享时的摘要展示。

首页 docs/index.soy 则使用{param navid: 'home' /}，页面模板会据此走专门的 landing-page 渲染分支。

文章中的内部链接写法

由于页面由模板渲染，正文内部不应写死绝对路径，而应复用__common.soy中提供的链接辅助模板，例如{call buck.ruleLink}{param name: 'java_library' /}{/call}渲染规则链接、{call buck.concept_link}...{/call}渲染概念链接、{call buck.cmd_link}{param name: 'build' /}{/call}渲染命令链接。这些辅助模板统一使用ROOT前缀拼接rule/{name}.html、concept/{page}.html、command/{name}.html等地址，保证部署在任意 ROOT 下链接都有效。

语法校验：别忘跑测试

新建或修改.soy后，仓库提供了自动化的语法检查。在 docs/BUCK 中定义了soy_docs_syntax这个python_test，它会用 docs/soy_syntax_check.py 校验docs/下所有*.soy文件（资源集合通过glob(["**/*.soy", "*.jar"])收集）。因此可以通过 Buck 测试命令验证文档源文件的正确性。

发布文档到 GitHub Pages

文档的公开托管走GitHub Pages，发布目标是仓库的gh-pages分支。整个过程由 docs/publish.sh 驱动。

发布命令

# 同时在后台构建文档（以 TCP 9814 端口提供渲染服务）并推送到 GitHub Pages cd docs ./publish.sh --start-soyweb

该脚本依赖 GitHub 交互，因此运行前需要配置好 GitHub 凭据（例如按照官方指南生成 SSH key 并添加到 ssh-agent）。

publish.sh 支持的参数

脚本执行流程详解

结合 docs/publish.sh 源码，一次发布实际经历以下步骤：

1. 预检查：先运行buck run //docs:generate_buckconfig_aliases生成最新别名；随后执行git diff --quiet，若仓库存在未提交改动则拒绝发布（Git repository is not clean; refusing to publish），保证发布内容与提交状态一致；
2. 准备临时目录：通过mktemp -d创建STATIC_FILES_DIR，用于存放 gh-pages 的干净检出；
3. （可选）启动渲染服务器：--start-soyweb时后台启动docs/soyweb-prod.sh，并轮询确认进程存活（2 秒超时判定）；
4. 获取 gh-pages 基址：脚本通过 HTTPS 凭据克隆仓库到临时目录，执行git checkout --orphan gh-pages创建孤儿分支，再用git rm -rf .清空内容（首次创建 gh-pages 分支时同样适用）；
5. 生成静态文档：调用./docs/soy2html.sh $STATIC_FILES_DIR渲染全部 HTML（详见下一节）；
6. 写入 CNAME 并提交：将buck.build写入CNAME文件，设置提交者为buck-bot（GIT_USER），以Updated HTML documentation.为提交信息提交；
7. 强制推送：执行git push origin gh-pages --force覆盖线上文档；
8. 失败兜底：脚本自嘲"并非无懈可击"，若推送失败会打印警告并建议前往仓库分支管理页面重试。

整个流程通过trap保证退出时清理临时文件并关闭 soyweb 后台进程。

团队协作约定

原文档特别强调一条理想实践：对 Buck 代码的改动，应在同一提交中同步更新相关文档。这样代码与文档的变更关系清晰可追溯，也避免文档滞后于实现。

Javadoc：本地生成与随文档发布

Buck 网站上的 Javadoc 会在每次发布文档时同步更新（由soy2html.sh自动完成）。本地生成 Javadoc 的方式如下（在 Buck 仓库根目录执行）：

ant javadoc-with-android

产物位于：

ant-out/javadoc-with-android/index.html

查看方式有两种：

1. 直接用浏览器打开ant-out/javadoc-with-android/index.html；
2. 复制到docs目录以复用本地文档服务器：

cp -r ant-out/javadoc-with-android/ docs/javadoc/

随后访问http://localhost:9811/javadoc即可在文档站点内浏览 Javadoc。

发布时 Javadoc 如何被纳入

在 docs/soy2html.sh 中，Javadoc 集成是发布流程的一环：

# 生成 javadoc 并纳入输出目录 ant javadoc-with-android mkdir -p "${OUTPUT_DIR}"/javadoc/ cp -r ant-out/javadoc-with-android/* "${OUTPUT_DIR}"/javadoc/

因此每次publish.sh发布时，Javadoc 都会被重新构建并一同推送到线上站点。

soy2html 静态化：.soy 如何变成 .html

发布流程的核心渲染步骤由 docs/soy2html.py 完成。它的工作逻辑值得理解：

1. 等待服务器就绪：pollForServerReady()最多等待 5 秒（每秒探测一次），直到http://localhost:9814/可访问；
2. 遍历渲染.soy：递归遍历docs/下所有不以__开头的.soy文件（__前缀表示共享模板而非独立页面），构造对应的.html路径，然后用curl --fail从 soyweb 服务器抓取渲染结果写入输出目录；
3. 复制静态资源：.css、.jpg、.js、.png、.gif、.html、.md、.svg、.ttf、.txt以及CNAME、.nojekyll等文件原样复制到输出目录。

注意soy2html.sh在调用 Python 脚本前会清空代理环境变量（HTTP_PROXY、HTTPS_PROXY等），因为脚本内部依赖curl直连本地服务器。

构建与校验支撑：docs/BUCK 中的自动化任务

docs/作为 Buck 仓库的一部分，其辅助工具以 Buck 规则声明在 docs/BUCK 中，实现了文档工程的自举：

这些任务说明文档维护本身也遵循 Buck 的"小模块、可复用、可测试"理念：生成、格式化、校验都被建模为可复用的构建目标。

适用前提与注意事项

• 必须在 Buck 仓库根目录运行：soyweb-local.sh、publish.sh、soy2html.sh均依赖git rev-parse --show-toplevel定位仓库根，再切换到docs/执行；
• 依赖本地 Buck 与 Java 环境：启动预览前会先执行buck run //docs:generate_buckconfig_aliases，随后用java -jar启动 plovr，因此需要已安装并配置好 Buck 和可用的 JDK；
• 端口占用：开发预览固定使用 9811，发布渲染固定使用 9814，若端口被占用需先释放或调整脚本参数；
• 发布有洁癖检查：publish.sh会拒绝在存在未提交改动时发布，请先提交代码与文档的变更；
• 发布涉及 GitHub 凭据：脚本通过 HTTPS 凭据克隆仓库并强制推送gh-pages，请确保凭据已配置且具备仓库写入权限。

至此，从一次简单的./docs/soyweb-local.sh本地预览，到新建文章、通过buck run/ant校验构建，再到./publish.sh --start-soyweb一键上线，Buck 文档工程的完整闭环已经打通。无论是为某个新构建规则补文档，还是修正既有命令参考，这套工作流都能保证文档与代码始终在同一节奏下演进。

• 开发工具
• 构建工具