RST 模板参考
==============

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

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

模板列表
--------

T_INDEX_DOC
~~~~~~~~~~~

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

.. code-block:: text

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

   ${modules_list}

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

T_MODULE_DOC
~~~~~~~~~~~~

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

.. code-block:: text

   ${module_head}

   ${module_body}

   .. toctree::
      :hidden:

   ${cmd_list}

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

T_MODULE_HEAD
~~~~~~~~~~~~~

模块页面的标题区。

.. code-block:: text

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

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

T_MODULE_BODY
~~~~~~~~~~~~~

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

.. code-block:: text

   ${cmds}

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

T_CMD_HEAD
~~~~~~~~~~

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

.. code-block:: text

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

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

T_CMD_BODY
~~~~~~~~~~

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

.. code-block:: text

   ${options}

变量：
  - ``options``：选项详细说明（由 ``T_OPTION_BODY`` 生成）。

T_OPTION_HEAD
~~~~~~~~~~~~~

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

.. code-block:: text

   `${name}`_
    ${description}

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

T_OPTION_BODY
~~~~~~~~~~~~~

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

.. code-block:: text

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

   .. _${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
~~~~~~~~~~~~

选项组约束信息。

.. code-block:: text

   :${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()`` 中：

.. code-block:: python

   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`` 变量。