Guidedog / 文档 0.2.0

命令行参考¶

guidedog 提供命令行工具，用于管理、构建、预览、翻译和转换文档项目。

基本语法¶

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

退出码¶

表 6 退出状态¶
退出码	条件
`0`	成功：所有操作均已完成，没有未处理的错误。
`1`	构建或转换失败，或 `-W` 将警告视为错误。
`2`	命令行语法、参数或选项有误。
`3`	达到配置的资源上限，或无法提供内存。
`4`	文件操作或外部编译器失败。
`5`	内部错误；诊断信息说明如何报告。
`70`	发生崩溃；此前发布的输出仍然可用。

命令概览¶

表 7 CLI 命令¶
命令	用途
`quickstart [DIR]`	创建文档项目，并生成可直接编辑的模板和配置。
`build [BUILDER] [DIR]`	按指定的输出格式构建文档项目。
`serve [DIR]`	启动本地 HTTP 预览服务器，并在文件修改后自动重建。
`clean [DIR]`	删除生成的构建产物和缓存。
`convert INPUT`	直接转换单个文件或标准输入。
`migrate [conf.py]`	将 Sphinx 的 `conf.py` 转换为声明式 `conf.toml`。
`intl <update\|stat>`	更新 PO 翻译目录，或报告翻译完成情况。
`formats`	列出内置的读取器、渲染器及格式符合性说明。
`gds <COMMAND>`	管理 Guidedog Discussions 的设计记录及其生命周期。

guidedog quickstart¶

创建项目目录，其中包含 conf.toml、index.rst、_templates/ 中的模板和 _static/ 中的样式：

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

选项：

-q: 静默模式；跳过交互提问，使用命令行提供的值。
-p, --project NAME: 设置项目显示名称。
-a, --author NAME: 设置作者或组织名称。
-v VERSION: 设置简短版本号，例如 1.0。
-r RELEASE: 设置完整发布标识，例如 1.0.0-rc1。
-l LANGUAGE: 设置项目默认语言，默认为 en。
--sep: 分别创建 source/ 和 build/ 目录，而不是将源文件放在根目录。
--suffix EXT: 设置源文档的默认扩展名，默认为 .rst。

guidedog build¶

协调读取源文件、解析目录树和交叉引用，以及发布最终产物：

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

支持的构建器：

html: 生成带搜索和导航的完整 HTML 网站。
dirhtml: 生成目录式 HTML 地址，例如 dir/index.html。
singlehtml: 将所有文档合并为一个 HTML 页面。
pdf: 用 Typst 排版 PDF 图书；别名为 latex 和 latexpdf。
text: 为每个文档生成纯文本文件。
gettext: 将可翻译的文本提取为 GNU gettext POT 模板。
dummy: 解析并检查文档树，不写入最终文件；用于语法检查。

构建选项：

-a: 写入所有输出文件，不考虑修改时间。
-E: 忽略缓存，从头重建环境。
-W: 将所有警告视为构建失败。
--keep-going: 配合 -W 使用时，继续处理剩余文档，退出前报告全部错误。
-n: 严格引用检查；对所有未解析的交叉引用给出警告。
-j N / -j auto: 设置并行解析线程数；auto 使用与 CPU 核心数相同的线程数。
-D name=value: 仅为本次运行覆盖 conf.toml 中的设置，例如 -D language=de。
-D table.key=value：只设置表类型设置（例如 html_context）中的一个键，并保留其他键，与 sphinx-build 相同。
-t TAG: 定义供 only 指令使用的条件标签。
-c DIR: 指定 conf.toml 所在的目录。
-C: 不读取任何 conf.toml 文件。
-v: 详细模式；显示提示信息和耗时统计。
-q: 静默模式；只显示警告和错误。
--color=always|never|auto: 控制终端的 ANSI 颜色输出。
--diagnostics=json: 向标准错误输出写入可供程序读取的 JSON 诊断信息。
--budget=MIB: 设置项目宿主持有的内存预算上限，默认为 1024 MiB。
--memory=ram|disk: 指定内存预算耗尽后的处理方式。
--untrusted: 省略原始嵌入标记，并禁用网络获取。这是能力限制策略，不是进程沙箱。

guidedog serve¶

启动本地 HTTP 服务器和文件监视器；源文档、模板或资源修改后，自动重建并刷新浏览器：

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

选项：

-p, --port PORT: 本地监听端口，默认为 8000。
--host HOST: 绑定的 IP 地址，默认为 127.0.0.1。

guidedog clean¶

删除构建目录及缓存的环境状态：

guidedog clean docs

guidedog convert¶

直接转换文件或标准输入，无需项目目录或配置：

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

选项：

-o, --output FILE: 输出文件路径；- 表示标准输出。
--to FORMAT: 目标格式：html、pdf 或 text；也可根据输出文件名推断。
--from FORMAT: 源读取器：rst、commonmark、myst 或 typst；也可根据输入扩展名推断。
--force: 覆盖已有输出文件，不再询问。
--strict: 出现任何警告即失败。
--raw=allow|omit: 控制原始嵌入代码的处理策略，默认为 omit。
--emit-typst FILE: 另存生成的中间 Typst 源码。

guidedog migrate¶

将 Sphinx 的 Python 配置文件 conf.py 转换为声明式 conf.toml：

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

选项：

-o FILE: 写入指定路径，或用 - 写入标准输出。
--force: 覆盖已有的 conf.toml。

guidedog intl¶

管理多语言文档的翻译目录：

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

intl update 的选项：

-l, --language LANG: 目标语言代码；可重复指定多种语言。
-p, --pot-dir DIR: 指定已提取的 POT 消息模板所在路径。

guidedog formats¶

显示已编译的读取器、渲染器、语法高亮器，以及规范测试的符合性结果：

guidedog formats

guidedog gds¶

管理 Guidedog Discussions 的架构设计提案（RFC）：

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback