taolib.testing.doc

taolib.testing.doc#

文档构建相关任务模块。

包含文档清理、构建、国际化、测试等相关任务以及文档站点配置集合创建功能。

Attributes#

`logger`
`PTY`
`ctx`

Classes#

`SphinxConfig`	Sphinx 配置数据类。
`ProjectConfig`	项目配置数据类。
`ProjectConfigValidator`	项目配置验证器。

Functions#

`_get_sphinx_paths`(→ tuple[str, str])	安全地从上下文获取 sphinx 的 source/target 路径，若没有 ctx.sphinx 则使用默认值。
`clean`(→ None)	清除文档构建目标目录，以便下次构建是干净的。
`_build_sphinx_opts`(→ tuple[str, str \| None])	构建 Sphinx 命令行选项字符串。
`build`(→ None)	构建项目的 Sphinx 文档。
`intl`(→ None)	更新 POT 文件并调用 sphinx-intl update 命令。
`doctest`(→ None)	运行 Sphinx 的 doctest 构建器进行文档测试。
`tree`(→ None)	显示文档目录的树形结构。
`serve`(→ None)	启动文档预览服务器。
`_build_single_project`(→ tuple[str, bool, str])	在子进程中构建单个 Sphinx 项目。
`build_parallel`(→ dict[str, bool])	并行构建多个 Sphinx 文档项目。
`_make_project_namespace`(→ invoke.collection.Collection)	为单个项目创建 Invoke 命名空间。
`create_docs`(…)	创建文档站点配置集合。
`sites`(→ invoke.collection.Collection)	创建文档站点配置集合。
`multi_sites`(→ invoke.collection.Collection)	创建多文档站点配置集合。

Module Contents#

taolib.testing.doc._get_sphinx_paths(ctx: invoke.context.Context, source: str | None, target: str | None) → tuple[str, str]#

安全地从上下文获取 sphinx 的 source/target 路径，若没有 ctx.sphinx 则使用默认值。

参数:

ctx -- Invoke 上下文对象，包含 sphinx 配置信息。
source -- 源目录路径，如果为 None 则使用配置值或默认值 'doc'。
target -- 目标目录路径，如果为 None 则使用配置值或默认值 'doc/_build/html'。

返回:

包含 source 和 target 路径的元组。

返回类型:

tuple[str, str]

taolib.testing.doc.logger#

taolib.testing.doc.PTY = True#

taolib.testing.doc.ctx = None#

class taolib.testing.doc.SphinxConfig#

Sphinx 配置数据类。

用于存储 Sphinx 文档构建的配置信息，包括源代码目录和构建输出目录。

source: str = 'doc'#

target: str = 'doc/_build/html'#

class taolib.testing.doc.ProjectConfig#

项目配置数据类。

用于存储单个文档项目的配置信息，包括名称、源代码目录、构建输出目录和子文档目录。

name: str#

source: str = 'doc'#

target: str = 'doc/_build/html'#

children: str = ''#

class taolib.testing.doc.ProjectConfigValidator#

项目配置验证器。

用于验证和规范化文档项目配置，支持从字典或 ProjectConfig 对象创建标准化配置。

static from_dict(data: dict, index: int = 0) → ProjectConfig#

从字典创建 ProjectConfig 对象。

参数:

data -- 包含项目配置的字典，应有 name、source、target、children 键。
index -- 配置在列表中的索引，用于生成默认名称。

返回:

标准化的 ProjectConfig 对象。

抛出:

ValueError -- 当必需字段缺失或格式不合法时。

static normalize(config: dict | ProjectConfig, index: int = 0) → ProjectConfig#

将配置标准化为 ProjectConfig 对象。

参数:

config -- 配置对象，可以是字典或 ProjectConfig 实例。
index -- 配置在列表中的索引，用于生成默认名称。

返回:

标准化的 ProjectConfig 对象。

taolib.testing.doc.clean(ctx: invoke.context.Context) → None#

清除文档构建目标目录，以便下次构建是干净的。

参数:: ctx -- Invoke 上下文对象，包含 sphinx 配置信息。

taolib.testing.doc._build_sphinx_opts(opts: str, language: str | None, nitpick: bool, jobs: str, keep_going: bool) → tuple[str, str | None]#

构建 Sphinx 命令行选项字符串。

参数:

opts -- 基础选项字符串。
language -- 文档语言。
nitpick -- 是否启用严格模式。
jobs -- 并行作业数。
keep_going -- 遇到错误是否继续。

返回:

(opts 字符串, language 路径后缀或 None)

taolib.testing.doc.build(ctx: invoke.context.Context, builder: str = 'html', opts: str = '', language: str | None = None, source: str | None = None, target: str | None = None, nitpick: bool = False, jobs: str = 'auto', keep_going: bool = True) → None#

构建项目的 Sphinx 文档。

参数:

ctx -- Invoke 上下文对象，包含 sphinx 配置信息。
builder -- Sphinx 构建器类型，默认为 'html'。
opts -- Sphinx 构建额外选项/参数。
language -- 文档语言，默认为 None。
source -- 源目录，覆盖配置设置。
target -- 输出目录，覆盖配置设置。
nitpick -- 是否启用更严格的警告/错误检查。
jobs -- 并行作业数，默认为 'auto'。
keep_going -- 遇到错误是否继续构建，默认为 True。

taolib.testing.doc.intl(ctx: invoke.context.Context, language: str = 'en') → None#

更新 POT 文件并调用 sphinx-intl update 命令。

用于更新多语言文档翻译。

参数:

ctx -- Invoke 上下文对象，包含 sphinx 配置信息。
language -- 目标语言代码，默认为 'en'（英语）。

taolib.testing.doc.doctest(ctx: invoke.context.Context) → None#

运行 Sphinx 的 doctest 构建器进行文档测试。

这将像测试运行一样，显示测试结果，如果所有测试未通过，则以非零状态退出。使用临时目录作为构建目标，因为唯一的输出是自动打印的文本文件。

参数:: ctx -- Invoke 上下文对象，包含 sphinx 配置信息。

taolib.testing.doc.tree(ctx: invoke.context.Context) → None#

显示文档目录的树形结构。

参数:: ctx -- Invoke 上下文对象，包含 sphinx 配置信息。

taolib.testing.doc.serve(ctx: invoke.context.Context, port: int = 8000) → None#

启动文档预览服务器。

参数:

ctx -- Invoke 上下文对象，包含 sphinx 配置信息。
port -- 服务器端口，默认为 8000。

taolib.testing.doc._build_single_project(source: str, target: str, builder: str, opts: str) → tuple[str, bool, str]#

在子进程中构建单个 Sphinx 项目。

参数:

source -- 文档源目录。
target -- 构建输出目录。
builder -- Sphinx 构建器类型。
opts -- Sphinx 命令行选项。

返回:

(项目标识, 是否成功, 输出信息)

taolib.testing.doc.build_parallel(project_configs: list[ProjectConfig] | dict[str, ProjectConfig], *, max_workers: int | None = None, builder: str = 'html', jobs: str = 'auto', keep_going: bool = True) → dict[str, bool]#

并行构建多个 Sphinx 文档项目。

使用 ThreadPoolExecutor + subprocess.run 实现并行构建，各项目在独立子进程中执行。

参数:

project_configs -- 项目配置列表或字典。
max_workers -- 最大工作进程数，默认为 None（由系统决定）。
builder -- Sphinx 构建器类型，默认为 'html'。
jobs -- 单项目内并行作业数，默认为 'auto'。
keep_going -- 遇到错误是否继续构建，默认为 True。

返回:

success_bool} 结果字典。

返回类型:

{project_name

taolib.testing.doc._make_project_namespace(project_config: ProjectConfig) → invoke.collection.Collection#

为单个项目创建 Invoke 命名空间。

参数:: project_config -- 项目配置数据类，包含名称、源目录、目标目录等。
返回:: 配置好的 Invoke Collection 对象，包含文档构建任务。

taolib.testing.doc.create_docs(source: str = 'doc', target: str = '.temp/html', children: str = '') → invoke.collection.Collection#

taolib.testing.doc.create_docs(source: list[dict[str, str]] | dict[str, dict[str, str]]) → invoke.collection.Collection

taolib.testing.doc.create_docs(source: list[ProjectConfig] | dict[str, ProjectConfig]) → invoke.collection.Collection

创建文档站点配置集合。

统一的文档站点配置创建函数，支持单个项目和多个项目的配置。

参数:

source -- 文档源代码目录或项目配置。可以是： - 字符串：文档源代码目录，默认为 'doc' - 列表：多个项目配置的列表，每个元素是包含 source、target、name 的字典 - 字典：多个项目配置的字典，键为项目名称，值为包含 source、target 的字典 - 列表[ProjectConfig]：多个项目配置的数据类列表 - 字典[str, ProjectConfig]：多个项目配置的数据类字典 - None：使用默认值 'doc'
target -- 文档构建输出目录，仅在处理单个项目时有效，默认为 '.temp/html'。
children -- 子文档目录，仅在处理单个项目时有效，如果指定则覆盖 source。

返回:

配置好的 Invoke Collection 对象，包含 doc 子命令或多个命名的 doc 子命令集合。

抛出:

ValueError -- 当项目配置不合法时。
TypeError -- 当配置类型不支持时。

taolib.testing.doc.sites(source: str = 'doc', target: str = 'doc/_build/html', children: str = '') → invoke.collection.Collection#

创建文档站点配置集合。

为不同的文档站点创建配置好的 Invoke 集合，用于构建 Sphinx 文档。

参数:

source -- 文档源代码目录，默认为 'doc'。
target -- 文档构建输出目录，默认为 '.temp/html'。
children -- 子文档目录，如果指定则覆盖 source。

返回:

配置好的 Invoke Collection 对象，包含 doc 子命令。

taolib.testing.doc.multi_sites(project_configs: list[dict[str, str]] | dict[str, dict[str, str]]) → invoke.collection.Collection#

创建多文档站点配置集合。

支持同时对多个 doc 项目进行构建的功能。

参数:: project_configs -- 项目配置列表或字典。可以是： - 列表形式：每个元素是包含 source、target、name 的字典 - 字典形式：键为项目名称，值为包含 source、target 的字典
返回:: 配置好的 Invoke Collection 对象，包含多个命名的 doc 子命令集合。