系统概述
========

RainaDoc 是一套基于 Python 和 Sphinx 的命令文档自动生成工具，用于自动生成基于 thor_core 派生的各种产品（如 RainaSynth、RainaSta、RainaPower）等工具的使用文档。它的核心思路是：

1. **定义即文档**：开发者在 XML 文件中描述命令（Command）、选项（Option）和选项组（Group）的结构与语义。
2. **自动生成 RST**：`doc_generator` 模块解析 XML 文件，通过 Python ``string.Template`` 模板引擎生成合法的 reStructuredText 文件。
3. **Sphinx 构建**：利用 Sphinx 将 RST 文件编译为 HTML、PDF、singlehtml 或 man page 等目标格式。

系统架构
--------

整个文档系统由以下几个层次组成，如下代码均位于 thor_core 仓库中。

.. code-block:: text

   Script/pyscripts/                 # 文档生成器源码
   ├── DocGenerator.py               # 入口脚本
   └── doc_generator/                # 核心模块
       ├── __init__.py
       ├── doc.py                    # RainaDoc / Module / CmdDoc 类
       ├── doc_template.py           # RST 模板定义
       └── xml.py                    # XML 解析（Cmd / Option / Group / Xml）

   doc/source/                       # Sphinx 源文件目录
   ├── conf.py                       # Sphinx 配置
   ├── index.rst                     # 文档首页
   ├── thor/                         # 自动生成的模块文档
   │   ├── index.rst
   │   └── cmds/                     # 各命令的详细文档
   └── ...

   doc/build/                        # Sphinx 构建输出
   └── html/                         # HTML 输出
   └── doctrees/                     # 中间 doctree 文件

工作流程
--------

1. **执行入口**：通过 ``build.py --doc {man / html / singlehtml / pdf}`` 触发文档构建流程。
2. **XML 加载**：``DocGenerator.py`` 收集 ``Script/source/CmdSource/`` 和 ``Sta/CmdSource/`` 等用户自定义的 cmd XML 文件。
3. **解析生成**：``RainaDoc.gen_module()`` 对每个 XML 调用 ``Xml`` 解析器，生成对应的 ``Module`` 对象，再为其中每个 ``Cmd`` 生成 ``CmdDoc`` 对象，最终写入 RST 文件到 ``source/thor/`` 目录。
4. **Sphinx 构建**：``RainaDoc.build()`` 调用 ``sphinx-build``（Windows 下通过 ``make.bat``，Linux 下通过 ``make``）触发 Sphinx 构建。

核心类关系
----------

.. code-block:: text

   RainaDoc                          # 主控制器，管理整个文档生成流程
   ├── Xml                           # 表示一个模块的 XML 定义
   │   └── Cmd                       # 表示模块下的一个命令
   │       ├── Option                # 命令的选项参数
   │       └── Group                 # 选项之间的约束关系组
   ├── Module                        # 文档生成中的模块实例
   │   └── CmdDoc                    # 文档生成中的命令实例
   └── (Templates)                   # RST 模板（在 doc_template.py 中定义）

为什么选择 reStructuredText
---------------------------

1. **可扩展**：后续可考虑测试结果 / simple case 等内容也支持 reStructuredText 并集成到 RainaDoc 中。
2. **支持文档间引用、搜索功能**：Sphinx 提供了强大的交叉引用和全文搜索。
3. **大型项目验证**：Linux、OpenCV、LLVM 等大型开源项目均使用其进行文档编写。