多语言文档站的荒野西部

📋 概述

technicalwriting.dev 讨论所谓"polyglot 文档站"：一个项目用 N 种语言提供库，文档站往往要对接 N 或 N+1 个文档生成器，而对外又需要统一的字体、配色与站内搜索体验。策略上大体只有两种。第一种是"变换"：解析各 API 生成器的输出，再转成主文档生成器能吃的标记——作者第一份工作就用 XSLT 把 Doxygen HTML 转成片段塞进 Sphinx，Breathe 走的也是这条路；代价是丢掉生成器对各自语言的理解、可能删掉用户真正需要的信息（Chesterton 的围栏），而且与生态习惯相悖。第二种是让生成器的原生 UI 直接嵌入主站，文中以 pigweed.dev 从 Breathe 转向该路线为例，理由包括构建变慢（约 90 秒降到 60 秒）与胶水代码过多导致静默失败。