使用方法

命令行触发

文档构建通过 build.py 的 --doc 参数触发，支持四种输出格式：

./build.py --doc html          # 构建多页面 HTML 文档
./build.py --doc singlehtml    # 构建单页面 HTML 文档
./build.py --doc pdf           # 构建 PDF 文档
./build.py --doc man           # 构建 man page 文档

独立运行

DocGenerator.py 也可以独立运行，直接生成文档：

# 使用默认 singlehtml 格式
python DocGenerator.py

# 指定输出格式
python DocGenerator.py html
python DocGenerator.py singlehtml
python DocGenerator.py pdf
python DocGenerator.py man

配置 XML 文件路径

XML 命令定义文件的扫描路径在 DocGenerator.py 的 build_doc() 函数中配置。默认扫描以下两个目录：

# DocGenerator.py 第 15-16 行
xml_files = []
xml_files.extend(Path("Script/source/CmdSource").glob("*.xml"))
xml_files.extend(Path("Sta/CmdSource").glob("*.xml"))

由于不同项目存放 XML 文件的路径不一致，研发人员需要根据自己的项目结构修改此处的路径配置。修改方式有两种：

直接修改源码：在 DocGenerator.py 中增删 xml_files.extend() 调用，将路径替换为实际存放 XML 的目录。

例如，如果项目将 XML 放在 src/cmds/ 目录下：
```
xml_files.extend(Path("src/cmds").glob("*.xml"))
```

添加多个扫描路径：一个项目可能有多个模块，各自有独立的 XML 目录：

xml_files.extend(Path("Script/source/CmdSource").glob("*.xml"))
xml_files.extend(Path("Sta/CmdSource").glob("*.xml"))
xml_files.extend(Path("gui/CmdSource").glob("*.xml"))
xml_files.extend(Path("physical/CmdSource").glob("*.xml"))

扫描到的 XML 文件会按路径排序后依次处理。

PDF 文档生成流程

Sphinx 原生的 PDF 构建（通过 pdflatex）依赖较多环境配置，且对中文支持不完善。因此推荐以下方式生成 PDF 文档：

步骤 1：在 EDA 研发服务器上生成 singlehtml

./build.py --doc singlehtml

此命令将生成单页面 HTML 文档，输出到 build/singlehtml/ 目录。 singlehtml 将所有内容合并到一个 index.html 文件中，便于后续转换为 PDF。

步骤 2：通过 SCP 传输到 Windows VDI

将生成的 singlehtml 目录从 EDA 研发服务器传输到用户的 Windows VDI 机器：

# 在用户 vdi 机器上的 cmd 中执行，替换以下参数：
# - user：EDA 服务器的用户名
# - eda_server_ip：EDA 服务器的 IP 地址
scp -r user@eda_server_ip:path/to/build/singlehtml/ destination/path/

具体示例：

scp -r tanlinfeng@192.168.15.99:/home/user/project/build/singlehtml/ Desktop/doc/

步骤 3：在浏览器中打开并保存为 PDF

在 Windows VDI 上找到传输过来的 singlehtml 目录，用浏览器打开 index.html。
在网页空白处右键，选择打印（或按 Ctrl+P ）。
在打印对话框中，目标打印机选择 另存为 PDF （或 Save as PDF ）。
点击 更多设置，勾选 背景图形 （或 保存背景图片），确保代码块等元素的背景色被保留。

可以在 pdf 输出页面勾选「保存背景图片」，代码块（ .. code-block:: ）和警告框等元素的背景色会在 PDF 中保存，提升阅读者的阅读体验。
点击保存，选择输出路径即可得到 PDF 文件。

DOC 编译执行流程

清理旧文件：RainaDoc.clean() 删除上次构建的输出目录。
收集 XML：扫描 Script/source/CmdSource/ 和 Sta/CmdSource/ 目录下的所有 .xml 文件并排序。
逐文件解析：对每个 XML 文件调用 RainaDoc.gen_module()：
1. 用 Xml 类解析 XML，提取模块名称、描述、命令列表。
2. 为每个 Cmd 创建 CmdDoc 对象，处理其 Option 和 Group。
3. 通过 string.Template 将数据填入 RST 模板。
4. 将生成的 RST 文件写入 source/thor/ 目录。
Sphinx 构建：调用 sphinx-build 或 make.bat 执行构建。

输出目录结构

doc/
├── source/
│   └── thor/
│       ├── index.rst              # thor 模块索引
│       ├── <module_name>.rst      # 各模块页面
│       └── cmds/
│           └── <cmd_name>.rst     # 各命令详情页
└── build/
    ├── html/                      # HTML 输出
    ├── doctrees/                  # 中间文件
    └── singlehtml/                # 单页 HTML 输出（如适用）

重复命令检测

thor_core 的 command 定义系统拥有同名指令检测，在 EDA 工具中，command 名称应当是唯一的，如果两个 XML 文件中定义了同名的 Command，解析器会抛出异常，确保文档中每个命令名的唯一性（通过 cmd_set 集合检测重复的命令名）。