API 参考

doc_generator.xml 模块

doc_generator.xml.check_file(file_path: Path)

检查文件是否存在且为普通文件。

Parameters:: file_path (pathlib.Path) – 文件路径。
Raises:: FileNotFoundError – 如果文件不存在或不是普通文件。

doc_generator.xml.check_bool(val)

将字符串转换为布尔值。

Parameters:: val (str) – 输入值，支持 "true", "false" 或空字符串。
Returns:: 对应的布尔值。
Return type:: bool
Raises:: AttributeError – 如果值不是 true 或 false。

class doc_generator.xml.Option

表示命令的一个选项参数。

name: str: 选项名称。

description: str: 选项描述。

type: str: 选项类型（BOOL / INT / FLOAT / STRING / LIST / GROUP），默认 "BOOL"。

default: str: 默认值。

positional: bool: 是否为位置参数。

internal: bool: 是否为内部选项（true 时不生成 usage 信息）。

process_default()

校验默认值是否符合类型约束。

BOOL 类型：值必须是 "true" 或 "false"。
INT / LONG / FLOAT 类型：值必须能通过 float() 转换。
LIST / GROUP 类型：不允许设置默认值。

Raises:: ValueError – 默认值不合法时抛出。

generate_usage()

生成命令 usage 字符串中的选项描述行。

Returns:: 格式化的 usage 字符串。
Return type:: str

class doc_generator.xml.GroupType

选项组约束类型枚举。

TYPE_NONE: 无约束。

TYPE_CONFLICT: 互斥约束（conflict）。

TYPE_DEPENDENT: 依赖约束（dependent）。

TYPE_LEAST: 至少一个约束（least）。

TYPE_TOGETHER: 同时出现约束（together）。

class doc_generator.xml.Group

表示选项之间的约束组。

name: str: 组名称。

type: GroupType: 约束类型。

target: str: 目标选项名。

options: list[str]: 组内选项名列表。

__contains__(option: Option)

判断某个 Option 是否属于该组。

Parameters:: option (Option) – 选项对象。
Returns:: 是否在组内。
Return type:: bool

class doc_generator.xml.Cmd

表示 XML 中定义的一个命令。

name: str: 命令名称。

description: str: 命令描述。

internal: bool: 是否为内部命令。

alias: str: 命令别名。

gourps: list[Group]: 关联的选项组列表。

options: list[Option]: 关联的选项列表。

class doc_generator.xml.Xml

表示一个模块的 XML 定义文件。

xml_path: pathlib.Path: XML 文件路径。

name: str: 模块名称（来自 <Module name="..."> 属性）。

description: str: 模块描述。

cmds: list[Cmd]: 模块下的命令列表。

cmd_sets: set[str]: 用于检测重名命令的集合。

doc_generator.doc 模块

class doc_generator.doc.CmdDoc

负责生成单个命令的 RST 文档内容。

xml: Cmd: 对应的 Cmd 解析对象。

options_list: list[str]: 选项摘要链接列表（由 T_OPTION_HEAD 生成）。

options_content: list[str]: 选项详细说明列表（由 T_OPTION_BODY 生成）。

add_option(option: Option)

将 Option 转换为 RST 内容，存入 options_list 和 options_content。

Parameters:: option (Option) – 选项对象。

get_opt_group_info(group: Group)

获取选项组的 RST 描述。

Parameters:: group (Group) – 选项组。
Returns:: RST 格式的组描述。
Return type:: str

generate()

生成命令页面的完整 RST 内容。

Returns:: (命令头部 RST, 命令选项详情 RST)。
Return type:: tuple[str, str]

class doc_generator.doc.Module

负责生成单个模块的 RST 文档内容。

xml: Xml: 对应的 Xml 解析对象。

cmds_dir: pathlib.Path: 存储命令子页面的目录路径。

cmds_list: list[str]: 命令索引条目列表。

add_cmd(cmd: Cmd)

为一个 Cmd 生成 RST 文件并记录索引条目。生成的文件写入 cmds_dir/<cmd.name>.rst。

Parameters:: cmd (Cmd) – 命令对象。

generate()

生成模块页面的完整 RST 内容。

Returns:: (模块头部 RST, 模块命令列表 RST)。
Return type:: tuple[str, str]

class doc_generator.doc.RainaDoc

文档生成系统的主控制器。

source_dir: pathlib.Path: 源文件根目录，默认为 Path("doc/source")。

build_dir: pathlib.Path: 构建输出根目录，默认为 Path("doc/build")。

doctrees_dir: pathlib.Path: 中间 doctree 目录。

thor_dir: pathlib.Path: 存储 thor 模块文档的输出目录。

cmd_set: set[str]: 全局命令名集合，用于重复检测。

init(): 初始化目录结构：清理并重建 doctrees_dir 和 thor_dir。

gen_module(xml: str)

解析 XML 文件并生成对应的 RST 模块文档。

Parameters:: xml (str) – XML 文件路径字符串。

build(builder='html')

调用 Sphinx 构建文档。

Windows 下执行：.\\make.bat <builder>
Linux 下执行：make <builder>
工作目录为 source_dir.parent

Parameters:: builder (str) – 构建目标格式，默认为 "html"。

clean(builder='')

清理构建输出。

若 builder 为空，执行 make clean。
若指定了 builder，删除 build_dir/<builder> 目录。

Parameters:: builder (str) – 构建目标格式。

doc_generator.doc_template 模块

该模块定义了一系列 string.Template 实例，用于生成 reStructuredText 文档片段。

doc_generator.doc_template.T_INDEX_DOC: string.Template: 文档首页 toctree 模板。

doc_generator.doc_template.T_MODULE_DOC: string.Template: 模块页面整体结构模板。

doc_generator.doc_template.T_MODULE_HEAD: string.Template: 模块标题模板。

doc_generator.doc_template.T_MODULE_BODY: string.Template: 模块命令列表模板。

doc_generator.doc_template.T_CMD_HEAD: string.Template: 命令标题模板。

doc_generator.doc_template.T_CMD_BODY: string.Template: 命令选项详情模板。

doc_generator.doc_template.T_OPTION_HEAD: string.Template: 选项摘要链接模板。

doc_generator.doc_template.T_OPTION_BODY: string.Template: 选项详细说明模板。

doc_generator.doc_template.T_GROUP_BODY: string.Template: 选项组约束信息模板。

DocGenerator 入口

DocGenerator.build_doc(format: str)

文档构建入口函数。

流程： 1. 创建 RainaDoc 实例。 2. 调用 raina.clean(format) 清理旧输出。 3. 收集 Script/source/CmdSource/ 和 Sta/CmdSource/ 下的 XML 文件。 4. 逐个调用 raina.gen_module() 生成 RST。 5. 调用 raina.build(format) 触发 Sphinx 构建。

Parameters:: format (str) – 输出格式（html / singlehtml / pdf / man）。