taolib.doc

文档构建相关任务模块。

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

Attributes

logger
PTY

Functions

_get_sphinx_paths(→ tuple[str, str])	安全地从上下文获取 sphinx 的 source/target 路径，若没有 ctx.sphinx 则使用默认值。
clean(→ None)	清除文档构建目标目录，以便下次构建是干净的。
build(→ None)	构建项目的 Sphinx 文档。
intl(→ None)	更新 POT 文件并调用 sphinx-intl update 命令。
doctest(→ None)	运行 Sphinx 的 doctest 构建器进行文档测试。
tree(→ None)
create_docs(…)	创建文档站点配置集合。
sites(→ invoke.collection.Collection)	创建文档站点配置集合。
multi_sites(→ invoke.collection.Collection)	创建多文档站点配置集合。

Module Contents

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

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

taolib.doc.logger

taolib.doc.PTY = True

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

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

参数:

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

taolib.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 -- 是否启用更严格的警告/错误检查

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

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

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

参数:

• ctx -- Invoke 上下文对象，包含 sphinx 配置信息

• language -- 目标语言代码，默认为 'en'（英语）

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

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

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

参数:

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

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

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

taolib.doc.create_docs(source: List[Dict[str, str]] | Dict[str, Dict[str, str]]) → invoke.collection.Collection

创建文档站点配置集合。

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

参数:

• source -- 文档源代码目录或项目配置。可以是： - 字符串：文档源代码目录，默认为 'doc' - 列表：多个项目配置的列表，每个元素是包含 source、target、name 的字典 - 字典：多个项目配置的字典，键为项目名称，值为包含 source、target 的字典 - None：使用默认值 'doc'

• target -- 文档构建输出目录，仅在处理单个项目时有效，默认为 '.temp/html'

• children -- 子文档目录，仅在处理单个项目时有效，如果指定则覆盖 source

返回:

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

taolib.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.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 子命令集合