sjtuhpc/texlive-sphinx

texlive-sphinx 镜像文档

镜像概述

texlive-sphinx是一个集成了texlive-full和Sphinx的Docker镜像，旨在为LaTeX文档提供便捷的CI（持续集成）构建环境。该镜像可直接用于自动化编译LaTeX文档或通过Sphinx生成技术文档，无需在CI环境中手动配置复杂的TeX依赖。Dockerfile托管于https://github.com/SJTU-HPC/texlive-sphinx%E3%80%82

核心功能与特性

• 完整TeX环境：内置texlive-full，包含LaTeX编译所需的全套宏包和工具（如pdflatex、xelatex等）。
• Sphinx支持：预安装Sphinx文档生成工具，可用于将reStructuredText或Markdown格式的源文件转换为HTML、PDF等多种输出格式。
• CI友好：轻量级设计，适合集成到各类CI/CD流程（如GitHub Actions、GitLab CI、Jenkins等）。

使用场景

• 自动化构建LaTeX学术论文、技术报告或书籍。
• 通过Sphinx生成开源项目的技术文档并输出为PDF或HTML。
• 在CI流程中验证LaTeX文档语法正确性及编译结果。

使用方法

基本使用（docker run）

编译LaTeX文档

将本地LaTeX项目目录挂载到容器的/workspace目录，执行编译命令：

bash
docker run --rm -v $(pwd):/workspace sjtu-hpc/texlive-sphinx pdflatex your_document.tex

• --rm：容器退出后自动删除。
• -v $(pwd):/workspace：将当前目录挂载到容器内的/workspace（工作目录）。
• pdflatex your_document.tex：执行LaTeX编译命令（可替换为xelatex、lualatex等）。

使用Sphinx生成文档

若项目使用Sphinx管理文档（如docs目录包含conf.py和源文件），可运行：

bash
docker run --rm -v $(pwd)/docs:/workspace sjtu-hpc/texlive-sphinx make html

生成的HTML文档将位于本地docs/_build/html目录。

Docker Compose配置（示例）

创建docker-compose.yml文件，定义LaTeX编译服务：

yaml
version: '3'
services:
  latex-build:
    image: sjtu-hpc/texlive-sphinx
    volumes:
      - ./:/workspace
    command: pdflatex main.tex

执行编译：

bash
docker-compose run --rm latex-build

环境变量（可选）

目前镜像未定义额外环境变量，所有配置通过挂载目录和命令行参数实现。

注意事项

• 确保挂载的本地目录包含完整的LaTeX源文件或Sphinx项目结构。
• 复杂LaTeX项目可能需要多次编译（如交叉引用、目录生成），可在命令中串联执行（如pdflatex main.tex && bibtex main && pdflatex main.tex && pdflatex main.tex）。