RST 模板参考

doc_template.py 中定义了所有的 reStructuredText 模板。这些模板使用 Python 标准库 string.Template 实现，通过 $variable 或 ${variable} 语法进行变量替换。

模板文件位置：doc_code/doc_generator/doc_template.py

模板列表

T_INDEX_DOC

用于生成文档首页的 toctree 目录树。

.. toctree::
   :maxdepth: 1
   :caption: Contents:

${modules_list}

变量：

modules_list：模块列表条目，每行一个 * :doc:`thor/<module_name>` 条目。

T_MODULE_DOC

模块页面的整体结构，包含模块头、模块体和隐藏的 toctree。

${module_head}

${module_body}

.. toctree::
   :hidden:

${cmd_list}

变量：

module_head：模块标题和描述（由 T_MODULE_HEAD 生成）。
module_body：命令列表（由 T_MODULE_BODY 生成）。
cmd_list：各命令页面的隐藏索引条目。

T_MODULE_HEAD

模块页面的标题区。

${name}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
${description}

变量：

name：模块名称，作为标题。
description：模块描述文本。

T_MODULE_BODY

模块页面中命令列表的容器。

${cmds}

变量：

cmds：命令链接条目，每行 * :doc:`cmds/<cmd_name>`。

T_CMD_HEAD

命令页面的标题区，包含命令名和各选项的摘要链接。

${name}
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
${options}

变量：

name：命令名称。
options：选项摘要链接（由 T_OPTION_HEAD 生成）。

T_CMD_BODY

命令页面中各选项详细说明的容器。

${options}

变量：

options：选项详细说明（由 T_OPTION_BODY 生成）。

T_OPTION_HEAD

选项的摘要链接行，显示在命令标题下方。

`${name}`_
 ${description}

变量：

name：选项名称（带 - 前缀）。
description：选项描述。

T_OPTION_BODY

选项的详细说明区域，包含属性表和关联选项信息。

-----------------

.. _${label}:

${name}
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

| ${description}

**attribute**

:type: ${type}
:positional: ${positional}
:default: ${default}

**related_options**

${related_options}

**simple case**

    There is currently no simple case.

变量：

label：交叉引用标签，格式为 <cmd_name>-<option_name>。
name：选项名称（带 - 前缀）。
description：选项描述。
type：选项类型（BOOL / INT / FLOAT / STRING / LIST / GROUP）。
positional：是否为位置参数（True / False）。
default：默认值。
related_options：关联的选项组信息（由 T_GROUP_BODY 生成）。

T_GROUP_BODY

选项组约束信息。

:${group_type}: ${options}

变量：

group_type：约束类型（TYPE_CONFLICT / TYPE_DEPENDENT / TYPE_LEAST / TYPE_TOGETHER）。
options：组内选项名列表，以空格分隔。

模板替换方式

doc.py 中使用两种模板替换方式：

``Template.substitute()``：严格替换，如果模板中存在未提供的变量，会抛出 KeyError。
``Template.safe_substitute()``：安全替换，未提供的变量会保留原始占位符，不会抛异常。

例如在 CmdDoc.add_option() 中：

option_head = T_OPTION_HEAD.substitute(
    name=f"-{option.name.strip()}",
    description=option.description,
)
option_body = T_OPTION_BODY.safe_substitute(
    name=f"-{option.name.strip()}",
    label=f"{self.xml.name}-{option.name.strip()}",
    description=option.description,
    positional=option.positional,
    type=option.type,
    default=option.default,
)

注意 option_body 使用 safe_substitute，因为后续还要通过二次 Template(option_body).substitute() 注入 related_options 变量。