系统概述

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

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

系统架构

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

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 文件

工作流程

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

核心类关系

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

为什么选择 reStructuredText

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