使用方法
========

命令行触发
----------

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

.. code-block:: shell

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

独立运行
--------

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

.. code-block:: shell

   # 使用默认 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()`` 函数中配置。
默认扫描以下两个目录：

.. code-block:: python

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

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

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

   例如，如果项目将 XML 放在 ``src/cmds/`` 目录下：

   .. code-block:: python

      xml_files.extend(Path("src/cmds").glob("*.xml"))

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

   .. code-block:: python

      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**

.. code-block:: shell

   ./build.py --doc singlehtml

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

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

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

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

具体示例：

.. code-block:: shell

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

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

1. 在 Windows VDI 上找到传输过来的 ``singlehtml`` 目录，用浏览器打开 ``index.html``。
2. 在网页空白处右键，选择 **打印** （或按 ``Ctrl+P`` ）。

   .. figure:: imgs/print_html.png
      :scale: 60%
      :alt: 右键菜单选择打印

3. 在打印对话框中，目标打印机选择 **另存为 PDF** （或 **Save as PDF** ）。

   .. figure:: imgs/select_pdf.png
      :scale: 60%
      :alt: 选择另存为 PDF

4. 点击 **更多设置**，勾选 **背景图形** （或 **保存背景图片**），确保代码块等元素的背景色被保留。

   .. figure:: imgs/change_setting.png
      :scale: 60%
      :alt: 更多设置

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

   .. figure:: imgs/add_backgroud.png
      :scale: 60%
      :alt: 勾选保存背景图形

5. 点击 **保存** ，选择输出路径即可得到 PDF 文件。

DOC 编译执行流程
--------------------------

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

4. **Sphinx 构建**：调用 ``sphinx-build`` 或 ``make.bat`` 执行构建。

输出目录结构
------------

.. code-block:: text

   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`` 集合检测重复的命令名）。