本页内容

Guidedog / 文档 0.2.0

维护本项目的文档

Guidedog 有三个项目：docs/manual、docs/api 和 docs/gds。手册和 GDS 均由 guidedog quickstart 创建。直接编辑生成的模板。不要把设计记录放进手册目录。

构建手册

在仓库根目录运行：

build/guidedog build html docs/manual -j auto -W
build/guidedog build pdf docs/manual -W
build/guidedog serve docs/manual

手册目录包含完整的 Odin API 参考。PDF 命令生成一本书，解释与声明相互链接。手册和独立 API 项目都从 lib/ 生成参考，无需维护复制的 API 稿件。

单独构建 API 项目：

build/guidedog build html docs/api -W
build/guidedog build pdf docs/api -W

构建并检查讨论文档

build/guidedog gds index
build/guidedog gds check
build/guidedog gds build --target=both

GDS CLI 管理元数据、编号、状态和恢复。RST 发布路径调用项目引擎，生成完整 HTML 网站及每条记录的独立 PDF。选择器仅限制 PDF 范围；HTML 始终保留完整目录和连贯网站。选定 PDF 的预览使用 _build/selected/<artifact>/pdf，不影响 _build/pdf 中的完整目录。

build/guidedog gds build guidedoc-odin --target=pdf
build/guidedog build html docs/gds -W
build/guidedog build pdf docs/gds -W

普通项目命令也适用。GDS 项目使用自己的 conf.toml 和 _build 目录。编写流程见 docs/gds/workflow.rst。

发布之前

检查链接和诊断。检查宽表格与代码块。修改排版后，将 PDF 页面渲染出来检查。HTML 要在桌面和手机宽度、浅色和深色模式下测试。确保离线时数学公式和图示仍能工作。修改引擎时，运行相关库测试和集成测试。