本页内容

Guidedog / 文档 0.2.0

迁移 Sphinx 项目

Guidedog 沿用 Sphinx 的项目结构和许多设置名称，但不运行 conf.py 或 Python 扩展。迁移应先把数据与可执行配置分开。

guidedog migrate path/to/conf.py
guidedog build html path/to/docs --diagnostics=json

migrate 读取字面量设置并写入 conf.toml。遇到需要人工选择的计算值，会给出报告。它不会导入项目或运行 Python 来求这些值。确认配置等价之前，先检查生成结果。

分三步完成

1. 先确保文档图正确，检查根文档、后缀、排除项和 include。
2. 再确保引用正确，检查领域、清单和自定义对象类型。
3. 最后确保呈现正确，检查模板、图表、公式及两种输出。

未知指令可能来自项目私有扩展。HTML 构建成功，并不能证明私有语义已复现。阅读诊断，再决定替换指令、配置受支持的别名，还是保留并记录限制。

受支持的功能，以及 CPython、Django 和 Flask 的验证证据，见 与 Sphinx 的兼容性。声明式自定义对象见 声明对象类型。