osgeo/proj-docs

PROJ文档构建容器

镜像概述和主要用途

本镜像为PROJ项目官方提供的文档构建专用容器，旨在统一文档构建环境，消除因本地环境差异导致的文档构建问题。通过封装文档构建所需的全部依赖和工具链，确保PROJ文档在不同环境下均能以一致的方式编译、生成和输出，简化文档构建流程并提升效率。

核心功能和特性

• 环境一致性：预配置PROJ文档构建所需的全部依赖（如编译器、渲染工具、样式处理器等），确保跨平台构建结果一致
• 文档构建支持：原生支持PROJ文档的编译、渲染和输出，兼容PROJ项目文档的格式规范
• 流程简化：内置文档构建脚本，减少手动配置步骤，一键完成文档生成
• 可扩展性：支持通过挂载外部配置文件或工具链，扩展文档构建能力

使用场景和适用范围

• 开发人员本地构建：PROJ项目开发人员在本地编写或修改文档后，通过容器快速构建并预览效果
• CI/CD集成：集成到PROJ项目的CI/CD流程中，实现文档的自动化构建、测试和部署
• 文档版本管理：在文档版本迭代或维护时，确保不同版本文档的构建环境一致
• 协作开发：团队协作中统一文档构建标准，避免因成员本地环境差异导致的构建失败

使用方法和配置说明

基本使用流程

1. 拉取镜像（假设镜像名为proj-docs-builder）：

   bash
   docker pull proj-docs-builder:latest
   

2. 运行容器构建文档（挂载本地文档目录至容器内工作目录）：

   bash
   docker run -it --rm \
     -v /path/to/local/proj-docs:/docs \  # 挂载本地PROJ文档目录
     proj-docs-builder:latest \
     make build  # 执行文档构建命令（具体命令需根据PROJ文档构建脚本调整）
   

关键配置说明

• 目录挂载：通过-v /local/path:/docs将本地文档目录挂载至容器内/docs目录（容器默认工作目录），确保容器可访问最新文档源文件
• 构建命令：容器支持通过命令行参数指定文档构建命令（如make build、sphinx-build等），具体命令需参考PROJ文档构建说明
• 环境变量（可选）：
  • DOC_OUTPUT_DIR：指定文档输出目录（默认：/docs/_build）
  • LOG_LEVEL：设置构建日志级别（可选值：info、debug，默认：info）

示例：本地构建PROJ文档

bash
# 假设本地PROJ文档位于~/proj/docs目录
docker run -it --rm \
  -v ~/proj/docs:/docs \
  -e DOC_OUTPUT_DIR=/docs/local_build \  # 指定输出到本地目录下的local_build文件夹
  proj-docs-builder:latest \
  sphinx-build -b html /docs/source /docs/local_build  # 使用sphinx构建HTML格式文档

构建完成后，生成的文档将位于本地~/proj/docs/local_build目录中，可直接通过浏览器打开预览。