API 参考 ======== doc_generator.xml 模块 ----------------------- .. py:module:: doc_generator.xml .. py:function:: check_file(file_path: Path) 检查文件是否存在且为普通文件。 :param file_path: 文件路径。 :type file_path: pathlib.Path :raises FileNotFoundError: 如果文件不存在或不是普通文件。 .. py:function:: check_bool(val) 将字符串转换为布尔值。 :param val: 输入值，支持 ``"true"``, ``"false"`` 或空字符串。 :type val: str :return: 对应的布尔值。 :rtype: bool :raises AttributeError: 如果值不是 true 或 false。 .. py:class:: Option :noindex: 表示命令的一个选项参数。 .. py:attribute:: name :type: str 选项名称。 .. py:attribute:: description :type: str 选项描述。 .. py:attribute:: type :type: str 选项类型（BOOL / INT / FLOAT / STRING / LIST / GROUP），默认 ``"BOOL"``。 .. py:attribute:: default :type: str 默认值。 .. py:attribute:: positional :type: bool 是否为位置参数。 .. py:attribute:: internal :type: bool 是否为内部选项（true 时不生成 usage 信息）。 .. py:method:: process_default() 校验默认值是否符合类型约束。 - ``BOOL`` 类型：值必须是 ``"true"`` 或 ``"false"``。 - ``INT / LONG / FLOAT`` 类型：值必须能通过 ``float()`` 转换。 - ``LIST / GROUP`` 类型：不允许设置默认值。 :raises ValueError: 默认值不合法时抛出。 .. py:method:: generate_usage() 生成命令 usage 字符串中的选项描述行。 :return: 格式化的 usage 字符串。 :rtype: str .. py:class:: GroupType :noindex: 选项组约束类型枚举。 .. py:attribute:: TYPE_NONE 无约束。 .. py:attribute:: TYPE_CONFLICT 互斥约束（conflict）。 .. py:attribute:: TYPE_DEPENDENT 依赖约束（dependent）。 .. py:attribute:: TYPE_LEAST 至少一个约束（least）。 .. py:attribute:: TYPE_TOGETHER 同时出现约束（together）。 .. py:class:: Group :noindex: 表示选项之间的约束组。 .. py:attribute:: name :type: str 组名称。 .. py:attribute:: type :type: GroupType 约束类型。 .. py:attribute:: target :type: str 目标选项名。 .. py:attribute:: options :type: list[str] 组内选项名列表。 .. py:method:: __contains__(option: Option) 判断某个 Option 是否属于该组。 :param option: 选项对象。 :type option: Option :return: 是否在组内。 :rtype: bool .. py:class:: Cmd :noindex: 表示 XML 中定义的一个命令。 .. py:attribute:: name :type: str 命令名称。 .. py:attribute:: description :type: str 命令描述。 .. py:attribute:: internal :type: bool 是否为内部命令。 .. py:attribute:: alias :type: str 命令别名。 .. py:attribute:: gourps :type: list[Group] 关联的选项组列表。 .. py:attribute:: options :type: list[Option] 关联的选项列表。 .. py:class:: Xml :noindex: 表示一个模块的 XML 定义文件。 .. py:attribute:: xml_path :type: pathlib.Path XML 文件路径。 .. py:attribute:: name :type: str 模块名称（来自 ```` 属性）。 .. py:attribute:: description :type: str 模块描述。 .. py:attribute:: cmds :type: list[Cmd] 模块下的命令列表。 .. py:attribute:: cmd_sets :type: set[str] 用于检测重名命令的集合。 doc_generator.doc 模块 ----------------------- .. py:module:: doc_generator.doc .. py:class:: CmdDoc :noindex: 负责生成单个命令的 RST 文档内容。 .. py:attribute:: xml :type: Cmd 对应的 Cmd 解析对象。 .. py:attribute:: options_list :type: list[str] 选项摘要链接列表（由 ``T_OPTION_HEAD`` 生成）。 .. py:attribute:: options_content :type: list[str] 选项详细说明列表（由 ``T_OPTION_BODY`` 生成）。 .. py:method:: add_option(option: Option) 将 Option 转换为 RST 内容，存入 ``options_list`` 和 ``options_content``。 :param option: 选项对象。 :type option: Option .. py:method:: get_opt_group_info(group: Group) 获取选项组的 RST 描述。 :param group: 选项组。 :type group: Group :return: RST 格式的组描述。 :rtype: str .. py:method:: generate() 生成命令页面的完整 RST 内容。 :return: ``(命令头部 RST, 命令选项详情 RST)``。 :rtype: tuple[str, str] .. py:class:: Module :noindex: 负责生成单个模块的 RST 文档内容。 .. py:attribute:: xml :type: Xml 对应的 Xml 解析对象。 .. py:attribute:: cmds_dir :type: pathlib.Path 存储命令子页面的目录路径。 .. py:attribute:: cmds_list :type: list[str] 命令索引条目列表。 .. py:method:: add_cmd(cmd: Cmd) 为一个 Cmd 生成 RST 文件并记录索引条目。生成的文件写入 ``cmds_dir/.rst``。 :param cmd: 命令对象。 :type cmd: Cmd .. py:method:: generate() 生成模块页面的完整 RST 内容。 :return: ``(模块头部 RST, 模块命令列表 RST)``。 :rtype: tuple[str, str] .. py:class:: RainaDoc :noindex: 文档生成系统的主控制器。 .. py:attribute:: source_dir :type: pathlib.Path 源文件根目录，默认为 ``Path("doc/source")``。 .. py:attribute:: build_dir :type: pathlib.Path 构建输出根目录，默认为 ``Path("doc/build")``。 .. py:attribute:: doctrees_dir :type: pathlib.Path 中间 doctree 目录。 .. py:attribute:: thor_dir :type: pathlib.Path 存储 thor 模块文档的输出目录。 .. py:attribute:: cmd_set :type: set[str] 全局命令名集合，用于重复检测。 .. py:method:: init() 初始化目录结构：清理并重建 ``doctrees_dir`` 和 ``thor_dir``。 .. py:method:: gen_module(xml: str) 解析 XML 文件并生成对应的 RST 模块文档。 :param xml: XML 文件路径字符串。 :type xml: str .. py:method:: build(builder="html") 调用 Sphinx 构建文档。 - Windows 下执行：``.\\make.bat `` - Linux 下执行：``make `` - 工作目录为 ``source_dir.parent`` :param builder: 构建目标格式，默认为 ``"html"``。 :type builder: str .. py:method:: clean(builder="") 清理构建输出。 - 若 ``builder`` 为空，执行 ``make clean``。 - 若指定了 builder，删除 ``build_dir/`` 目录。 :param builder: 构建目标格式。 :type builder: str doc_generator.doc_template 模块 -------------------------------- .. py:module:: doc_generator.doc_template 该模块定义了一系列 ``string.Template`` 实例，用于生成 reStructuredText 文档片段。 .. py:data:: T_INDEX_DOC :type: string.Template 文档首页 toctree 模板。 .. py:data:: T_MODULE_DOC :type: string.Template 模块页面整体结构模板。 .. py:data:: T_MODULE_HEAD :type: string.Template 模块标题模板。 .. py:data:: T_MODULE_BODY :type: string.Template 模块命令列表模板。 .. py:data:: T_CMD_HEAD :type: string.Template 命令标题模板。 .. py:data:: T_CMD_BODY :type: string.Template 命令选项详情模板。 .. py:data:: T_OPTION_HEAD :type: string.Template 选项摘要链接模板。 .. py:data:: T_OPTION_BODY :type: string.Template 选项详细说明模板。 .. py:data:: T_GROUP_BODY :type: string.Template 选项组约束信息模板。 DocGenerator 入口 ------------------ .. py:module:: DocGenerator .. py:function:: 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 构建。 :param format: 输出格式（html / singlehtml / pdf / man）。 :type format: str