Guidedog / 文档 0.2.0

配置参考¶

每个 Guidedog 项目都使用根目录下的 conf.toml。配置是声明式 TOML 数据，不会执行任意代码。

许多配置键与 Sphinx 的 conf.py 变量对应，因此可用 guidedog migrate conf.py 辅助迁移。

最小配置¶

项目只需基本信息。省略的设置使用默认值：

project = "Field Notes"
author = "Your Name"
version = "1.0"
release = "1.0.0"
language = "en"
root_doc = "index"
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
html_static_path = ["_static"]
pdf_paper_size = "a4"

项目元数据¶

表 8 元数据选项¶
键	类型	默认值	说明
`project`	字符串	`"Python"`	供读者识别的项目名称。
`author`	字符串	`""`	作者或组织名称。
`copyright`	字符串	`""`	显示在页脚的版权声明。
`version`	字符串	`""`	简短版本号，例如 `"1.0"`。
`release`	字符串	`""`	完整版本号，可包含 alpha 或 beta 标识，例如 `"1.0.0b1"`。
`language`	字符串	`"en"`	用于排版、断词和翻译的 ISO 语言代码，例如 `"de"` 或 `"zh_CN"`。
`today`	字符串	`""`	自定义日期文字；省略时用 `today_fmt` 格式化当前日期。
`today_fmt`	字符串	`""`	文档日期的格式字符串。

常规选项¶

表 9 发现与解析选项¶
键	类型	默认值	说明
`root_doc`	字符串	`"index"`	作为根目录的文档。
`source_suffix`	数组	`[".rst"]`	可作为文档源文件读取的扩展名。
`exclude_patterns`	数组	`[]`	发现源文件时排除的目录和文件通配符模式。
`include_roots`	数组	`[]`	允许包含源文件的外部目录。
`templates_path`	数组	`[]`	HTML 和 PDF 模板目录；优先于内置模板。
`extensions`	数组	`[]`	启用受支持的内置 Sphinx 扩展，例如 `"sphinx.ext.autodoc"`。
`primary_domain`	字符串	`"py"`	未写前缀的指令和角色所用的默认域，例如 `"py"`、`"c"` 或 `"odin"`。
`highlight_language`	字符串	`"default"`	代码块未指定语言时使用的默认语言。
`pygments_style`	字符串	`""`	浅色主题使用的 Pygments 高亮样式。
`pygments_dark_style`	字符串	`""`	深色主题使用的语法高亮样式。
`smartquotes`	布尔值	`true`	将直引号和连字符转换为排版用标点。
`rst_prolog`	字符串	`""`	添加到每个文档开头的 reStructuredText 片段。
`rst_epilog`	字符串	`""`	添加到每个文档末尾的 reStructuredText 片段。

编号与数学¶

表 10 编号选项¶
键	类型	默认值	说明
`numfig`	布尔值	`false`	启用后自动为图、表和代码块编号。
`numfig_secnum_depth`	整数	`1`	图编号包含的章节层级；例如 `1` 可生成 `Fig. 2.1`。
`numfig_format`	表	见下文	`"figure"`、`"table"` 和 `"code-block"` 的编号前缀格式。
`math_number_all`	布尔值	`false`	启用后自动为所有独立公式编号。
`math_eqref_format`	字符串	`"({number})"`	`:eq:` 公式引用的格式字符串。
`mathjax_path`	字符串	URL	MathJax JavaScript 文件的 CDN 地址或本地路径。

numfig_format 的默认值：

[numfig_format]
figure = "Fig. %s"
table = "Table %s"
code-block = "Listing %s"
section = "Section %s"

诊断与严格检查¶

表 11 诊断选项¶
键	类型	默认值	说明
`nitpicky`	布尔值	`false`	对未解析的交叉引用和失效目标发出警告。
`nitpick_ignore`	数组	`[]`	免于严格引用警告的 `[type, target]` 配对数组。
`suppress_warnings`	数组	`[]`	不应报告的警告类别代码。
`keep_warnings`	布尔值	`false`	在发布的文档中保留警告。

HTML 输出选项¶

表 12 HTML 选项¶
键	类型	默认值	说明
`html_theme`	字符串	`"guidedog"`	生成 HTML 时使用的主题。
`html_theme_options`	表	`{}`	传递给 HTML 主题的键值选项。
`html_title`	字符串	自动推导	浏览器标签页显示的标题。
`html_short_title`	字符串	自动推导	导航路径中使用的简短标题。
`html_logo`	字符串	`""`	相对于源目录的项目标志图片路径。
`html_favicon`	字符串	`""`	网站图标文件路径。
`html_static_path`	数组	`[]`	复制到输出 `_static/` 目录的文件夹。
`html_extra_path`	数组	`[]`	原样复制到输出根目录的文件夹。
`html_css_files`	数组	`[]`	HTML 页面加载的自定义 CSS 文件名。
`html_js_files`	数组	`[]`	HTML 页面加载的自定义 JavaScript 文件名。
`html_permalinks`	布尔值	`true`	为段落和章节添加固定链接。
`html_permalinks_icon`	字符串	`"¶"`	固定链接使用的符号或文字。
`html_baseurl`	字符串	`""`	站点地图和元数据使用的规范基础 URL。
`html_context`	表	`{}`	供 Jinja 模板使用的自定义变量字典。
`html_additional_pages`	表	`{}`	自定义页面：`{ "page_name" = "template.html" }`。

PDF 与 Typst 选项¶

表 13 PDF 选项¶
键	类型	默认值	说明
`pdf_paper_size`	字符串	`"a4"`	纸张格式：`"a4"` 或 `"us-letter"`。
`pdf_logo`	字符串	`""`	图书封面的标志图片路径。
`pdf_toplevel_sectioning`	字符串	`"chapter"`	对应图书分层的章节级别：`"chapter"` 或 `"part"`。
`pdf_show_urls`	字符串	`"no"`	打印版的网址显示方式：`"no"`、`"inline"` 或 `"footnote"`。
`pdf_preamble`	字符串	`""`	插入生成文档头部的原始 Typst 源码。
`pdf_font_paths`	数组	`[]`	查找自定义 OTF/TTF 字体的附加目录。
`pdf_packages`	字符串	`"download"`	包解析策略：`"download"` 或 `"offline"`。
`typst`	字符串	`"typst"`	系统 Typst CLI 的程序名或绝对路径。

定义 PDF 图书¶

[[pdf_documents]] 表定义项目要生成的一本或多本图书：

[[pdf_documents]]
root = "index"
file = "guide.pdf"
title = "Field Notes Complete Guide"
author = "Author Name"

[[pdf_documents]]
root = "reference/index"
file = "reference.pdf"
title = "Field Notes Reference"
author = "Author Name"

MyST Markdown 选项¶

表 14 MyST Markdown 选项¶
键	类型	默认值	说明
`myst_enable_extensions`	数组	`["dollarmath"]`	语法扩展：`"colon_fence"`、`"deflist"`、`"dollarmath"`、`"fieldlist"`、`"tasklist"`、`"substitution"`。
`myst_heading_anchors`	整数	`0`	自动生成标题锚点的层级深度；`0` 表示禁用。
`myst_substitutions`	表	`{}`	Markdown 文档可使用的变量替换，例如 `{key = "value"}`。
`myst_url_schemes`	数组	`["http", ...]`	识别为外部链接的 URI 协议。
`myst_commonmark_only`	布尔值	`false`	仅使用 CommonMark 语法，不启用 MyST 扩展。

Intersphinx 选项¶

extensions = ["sphinx.ext.intersphinx"]
intersphinx_cache_limit = 5
intersphinx_timeout = 30

[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]

完整流程见链接到其他项目。

Python autodoc 选项¶

表 15 Autodoc 选项¶
键	类型	默认值	说明
`autodoc_source_paths`	数组	`[]`	供静态分析查找 Python 模块的目录。
`autoclass_content`	字符串	`"class"`	类文档字符串的来源：`"class"`、`"init"` 或 `"both"`。
`autodoc_member_order`	字符串	`"alphabetical"`	成员排序方式：`"alphabetical"`、`"bysource"` 或 `"groupwise"`。
`autodoc_typehints`	字符串	`"signature"`	类型提示的位置：`"signature"`、`"description"` 或 `"none"`。
`autodoc_default_options`	表	`{}`	所有 `auto*` 指令使用的默认选项。

完整发现规则见用 autodoc 编写 Python 文档。

Odin API 文档选项¶

表 16 Odin 域选项¶
键	类型	默认值	说明
`odin_autoapi_dirs`	数组	`[]`	扫描 Odin 包的源目录。
`odin_autoapi_root`	字符串	`"api"`	生成 Odin API 文档的目标子目录。
`odin_autoapi_options`	数组	`["members", "undoc-members"]`	筛选要包含的成员。
`odin_autoapi_member_order`	字符串	`"source"`	成员排序方式：`"source"` 或 `"alphabetical"`。

Odin 域的完整用法见为 Odin 生成文档。

国际化选项¶

表 17 i18n 选项¶
键	类型	默认值	说明
`locale_dirs`	数组	`["locales"]`	查找 gettext 翻译目录的文件夹。
`gettext_compact`	布尔值	`true`	将同一目录内文档的消息合并到一个翻译目录。
`gettext_uuid`	布尔值	`false`	在 POT 消息中写入稳定的 UUID。
`gettext_auto_build`	布尔值	`true`	构建时将 `.po` 编译为二进制 `.mo` 目录。
`figure_language_filename`	字符串	`"{root}.{language}{ext}"`	选择本地化图片的文件名模板。

翻译流程见国际化。