本页内容

Guidedog / 文档 0.2.0

与 Sphinx 的兼容性

在有助于作者迁移项目的地方，Guidedog 遵循 Sphinx，并逐项衡量兼容性。它不执行 Python 配置或任意 Python 扩展。构建成功只能证明构建完成，不能证明完全等价。

项目与发布

表 20 项目操作

操作	已实现的行为
项目布局与构建参数	采用 Sphinx 风格的源目录、输出目录及参数：-a -E -W -n -D -t -j -b -M -c -C。
配置	使用熟悉的 Sphinx 设置名，以 TOML 数据配置。迁移时转换字面量，并报告需要计算的值。
HTML 构建器	支持 html、dirhtml 和 singlehtml。单页锚点包含文档名称。
其他构建器	支持 text、gettext 和 dummy。pdf 使用 Typst；latex 和 latexpdf 也选择这条处理路线。
模板	Guidedog 自带的 Jinja 实现、保留类型的 html_context、布局继承及附加页面。
增量构建	源文件、依赖项、模板、配置和引用查询的变化，使受影响的输出失效。
发布	一次发布完整的一代输出。构建失败时保留上一代已发布内容。

-D 的布尔值接受 true、false 或 1、0。若项目有 contents 而没有 index，可将 contents 作为根文档，但会给出警告。附加模板页面放在站点根目录，即使使用 dirhtml 也是如此。具体约定见 模板。

未变化的页面也会再次报告诊断，因此 -W 在全新构建和未变化的构建中含义一致。删除文档后，其页面也会移除。发布使用可恢复的日志；若提交中断，下次构建会完成恢复。不变式及平台边界见 发布完整的一代输出。

不提供 epub、man、texinfo、linkcheck、doctest、coverage 和 changes 构建器。使用这些名称时会给出纠正说明。仓库中的 tools/linkcheck 是独立的验证工具。

源文件语言

表 21 固定版本的一致性验证

读取器	证据与限制
reStructuredText	98 个语料源文件与对照的 Docutils 树及标识符一致。对比不包括源码位置和若干内部管理属性。
CommonMark 0.31.2	全部 652 个规范示例通过测试。
MyST 0.16.1 reference	218 个读取器测试样例中有 215 个一致，10 个 Sphinx 构建样例中有 8 个一致。其余差异均已记录。

这些测试使用固定版本，不能据此推断与所有后续版本兼容。运行 guidedog formats 可查看当前可执行程序的读取器和渲染器验证信息。各读取器目录还包含一致性说明。

rst_prolog 插在开头的书目信息字段之后，rst_epilog 插在源码末尾，两者均不插入 Markdown。条件成立时，only 和 ifconfig 保留其中的章节。若条件章节改变了周围的章节层级，其位置可能与 Sphinx 不同。MyST 的 eval-rst 内不允许章节标题，会报告错误。

引用与领域

Guidedog 实现了 toctree、标签、术语表、章节与插图编号，以及 ref、doc、numref、term、download、any、keyword、option、envvar 和 token 引用。对象可以出现在目录树、侧边栏和页面大纲中。

已实现标准、Python、C、C++、JavaScript、reStructuredText 和数学领域。Odin 领域是 Guidedog 自有的扩展，描述包、声明、签名及生成的 API 页面。仅基于源码的发现机制及其限制见 为 Odin 生成文档。

参数、返回值、异常和变量字段组成结构化描述。规范名称成为引用和清单中的别名。Python 默认值和注解保留源码写法；Sphinx 可能通过 Python 的反解析器重新打印。C++ 声明发布与 Sphinx 兼容的标识符版本和符号清单。仍有嵌套深度限制。嵌套括号的解析时间为线性。

numref 替换一个编号占位符，并报告未编号的目标。章节按阅读顺序编号。每份文档只编号一次；第二个编号目录树会报告冲突。格式替换和标识符细节见引用测试。

内置通用索引、模块索引和搜索。搜索匹配词语前缀，不采用 Sphinx 的英语词干算法。

声明式对象类型可替代一类常用的 Python 扩展注册。object_types、crossref_types 和 directive_aliases 描述相应数据。自定义 Python parse_node 改为声明式的名称、显示和程序规则。迁移会报告无法表达的代码。参见 声明对象类型。

内置扩展的行为

表 22 扩展的边界

行为	状态
todo, ifconfig, extlinks, autosectionlabel	内置支持。对硬编码的 extlinks 链接，可建议改用角色。
graphviz	链接的 Graphviz 库生成静态图形，并遵守资源访问边界。
intersphinx	支持本地和获取的清单。Windows 当前仅支持本地文件。
githubpages	内置静态站点所需的发布文件。
mathjax 和 imgmath	HTML 公式使用 MathJax。PDF 将支持的 LaTeX 子集转换为 Typst。
myst_parser	已实现的项目级 Markdown 层。
doctest 指令	显示内容。项目构建器不执行其中的测试。
autodoc	读取 Python 源码，不导入或执行包。

基于源码的 autodoc 无法发现所有运行时创建的对象。编译模块、外部装饰器、计算所得的值及扩展事件钩子都有明确限制。参考行为来自 Python 3.13 和固定版本的 Sphinx 文档生成器测试。完整设置及例外见 用 autodoc 编写 Python 文档。

autosummary、napoleon、viewcode 和任意 Python 扩展不属于这条处理路线。配置中出现不支持的扩展时会报告；未知指令或角色会在源码位置报告。发布之前必须检查被省略的内容。其他主题名称会被接受，但使用 Guidedog 自有的主题实现。

信任与资源限制

普通构建接受项目的原始 HTML、Typst、模板和网络清单。本地读取限于源目录及明确共享的根目录。符号链接不能扩大权限。模板、静态文件、include、图片、字体和 API 源码均遵守同一规则。

Graphviz 图片资源相对于所属文档解析，并受路径边界限制。支持的图片数据会嵌入图形。imagepath 和 fontpath 不会扩大边界。Typst 在包含可读目录的专用根目录中运行，确保图书模板及前置内容仅访问声明的资源。

--untrusted 将读取范围缩至源目录，省略原始内容、不安全 URL、外部资源、项目 Typst 模板和前置内容，并给出诊断。它不获取清单或 Typst 包。请求读取资源的图表会以代码显示，并给出警告。此模式不限制原生编译器的内存或运行时间。

主机预算默认为 1 GiB，分配前先预留额度。页面工作区使用后释放；项目增大时，保留的项目图和清单仍会占用内存。读取工作线程协调任务准入。请求被拒绝时，会指出失败操作及可用的纠正选项。

--memory=ram 在托管预算达到上限时停止。--memory=disk 允许托管工作存储使用内存映射的临时文件；保留的主机存储仍计入 RAM 预算。--disk-budget 限制映射存储，策略还保留磁盘余量。非交互命令不会等待回答。可通过 GUIDEDOG_AVAILABLE_MIB 提供已知的机器可用容量。

--max-depth、--max-nodes 和 --stack-kib 限制文档处理。改变限制会使读取缓存和输出缓存失效。深度与栈容量必须匹配。原生 Graphviz、tree-sitter 和 Typst 的分配不属于主机预算；若需硬性上限，应使用操作系统限制。参见 错误信息 和 内存与所有权。

验证与实际项目

tools/sphinxdiff 对比 42 个固定版本的 Sphinx 测试根目录，检查页面、标识符、正文链接、清单、编号及诊断。存储的结果及其 README 解释了有意保留的差异，例如更精确的源码位置、稳定的阅读顺序编号，以及对省略的目标专用原始内容给出明确报告。

2026 年 10 月 1 日的远程验证对 CPython、Django 和 Flask 执行了全新及未变化的 HTML、PDF 构建。全部十二次构建成功，诊断和链接结果保持基线一致。另有 1,039 项 Linux 测试和 94 项针对性 AddressSanitizer 测试通过。

这些项目含有不支持的 Python 扩展结构，其诊断仍是验证证据的一部分。退出状态为零不表示所有私有指令都已复现。若发布要求零诊断，请使用 -W。

历史测量和源码修订记录保存在 docs/manual/evidence/manuals.md。最新远程评审报告位于 build/review-remote-20261001/report.txt。这些数据描述的是记录的工作负载，并非普遍适用的速度或内存上限。