linuxserver/doc-builder

linuxserver/doc-builder 镜像文档

镜像概述和主要用途

linuxserver/doc-builder 是 LinuxServer.io (LSIO) 内部 CI 流程的专用组件，用于自动化文档生成。该镜像不供公开使用，主要服务于 LSIO 团队的持续集成流程，实现文档的自动化构建与管理。

核心功能和特性

• 文档自动化生成：基于配置文件（如 readme-vars.yml）生成标准化 Markdown 文档（输出为 GENERATED.md）。
• CI 流程集成：无缝对接 LSIO 内部 CI 系统，支持在 CI 环境中自动执行文档构建任务。
• 本地测试支持：提供本地运行模式，便于开发人员在本地环境测试文档生成逻辑。

使用场景和适用范围

适用场景

• LSIO 内部 CI/CD 流水线：作为自动化流程的一环，在代码构建或部署阶段自动更新文档。
• 本地文档开发测试：LSIO 团队成员在本地修改文档配置后，快速验证生成效果。

适用范围

仅限 LSIO 内部团队使用，不对外提供公开服务或支持。

详细使用方法和配置说明

环境要求

• Docker 环境（支持 docker run 命令）。
• 需准备文档配置文件（如 readme-vars.yml，具体格式由 LSIO 内部规范定义）。

运行方式

1. 远程（CI 环境）运行

在 LSIO CI 流程中使用，需指定容器名称和临时目录挂载。

命令示例：

bash
docker run --rm \
  -e CONTAINER_NAME=${CONTAINER_NAME} \  # CI 环境中指定容器名称（内部变量）
  -v ${TEMPDIR}:/ansible/readme \        # 挂载临时目录至容器内文档处理路径
  linuxserver/doc-builder:latest

参数说明：

• -e CONTAINER_NAME=${CONTAINER_NAME}：环境变量，传递 CI 环境中的容器名称，用于文档生成时的上下文标识（具体作用由 LSIO 内部逻辑定义）。
• -v ${TEMPDIR}:/ansible/readme：挂载主机临时目录（${TEMPDIR}）至容器内 /ansible/readme 路径，用于读取文档配置文件和输出结果。

2. 本地运行（测试用）

供 LSIO 团队成员在本地测试文档生成功能，需挂载当前工作目录并启用本地模式。

前置条件：
本地目录中存在 readme-vars.yml 文件（符合 LSIO 内部文档配置规范）。

命令示例：

bash
docker run --rm \
  -v $(pwd):/tmp \  # 挂载当前工作目录至容器内 /tmp 路径
  -e LOCAL=true \   # 启用本地模式
  linuxserver/doc-builder:latest

输出说明：
执行后，生成的 Markdown 文档 GENERATED.md 将保存至本地当前工作目录。

关键配置参数

注意事项

• 该镜像为 LSIO 内部专用工具，不提供公开文档或技术支持。
• 本地测试需确保 readme-vars.yml 格式符合 LSIO 内部规范，否则可能导致生成失败。
• 输出文件 GENERATED.md 的内容结构由镜像内置逻辑决定，具体规则需参考 LSIO 内部文档标准。