本页内容

Guidedog / 文档 0.2.0

项目如何工作

项目根目录是包含 conf.toml 的目录。root_doc 指定阅读顺序起点。Guidedog 发现并读取源文档、解析关系，发布完整输出版本。

图 2 构建将发现、语义、呈现和发布分开。

文档与资源

文件后缀选择读取器。RST 和项目 Markdown 共享项目图。图片和下载是资源；Guidedog 复制文档使用的资源。主题资源列于 html_static_path。包含文件必须位于源目录或配置的 include_roots 内。

独立的项目

手册与设计记录应放在独立项目中：读者和阅读顺序不同。各自拥有配置、模板、缓存和输出。Guidedog 的 docs/manual 与 docs/gds 即采用此方式。

增量构建

Guidedog 记录各输出使用的输入和查找结果。源文件改变会重读，依赖改变使使用者失效，模板改变可影响每页。未变文档可从保存对象加载。

缓存是上次构建的证据，不是事实来源。-E 丢弃下次构建使用的保存环境，-a 写出所有输出。它们解决不同问题。

\[\text{可复用} = \text{输入相同} \land \text{查找结果相同} \land \text{输出存在}\]

模板中的显式时间戳也是页面输入。即使文字未变，打印当前分钟的页面也可能改变。需要固定构建时间时，用 SOURCE_DATE_EPOCH。

发布

构建将变化写入同级暂存目录，完成目录、刷写文件和记录后，再切换版本。读者看到完整旧版或新版。中断的提交在下次构建处理。设计和证明义务见 发布完整的一代输出。