Git、Docker 和 TeX 文档的持续集成

Git、Docker 和持续集成 (CI) 的强大功能可以用于简化 TeX 文档的编译，同时跟踪不同的变体和版本。基于这些技术，可以开发一个灵活的工作流程，以反映 TeX 文档中连续的更改，并在每个 PDF 中体现出来，版本号递增，例如 document-v4.pdf。因此，让我们创建一个可以自动执行此过程的工作流程。

1. 目标

使用 Git、Docker 和持续集成 (CI) 构建 TeX 文档，并将 PDF 上传到 Dropbox，并具有适当的分支结构和版本控制。

2. 工作流程

3. 要求

我们需要：

1. Git 服务
   • Bitbucket
   • GitHub
2. 持续集成和部署服务
   • Semaphore
   • Travis
3. Dropbox 帐户

3.1. Dropbox Uploader

注意： 在配置 Dropbox API 时，建议使用仅应用文件夹作为访问级别。

为了将生成的 PDF 上传到 Dropbox，我们将使用 Dropbox Uploader。

1. 请按照 Dropbox Uploader 的 README.md 在本地机器上进行配置。
2. 验证您的本地机器上是否拥有 ~/.dropbox_uploader 文件。我们稍后将使用此文件。

4. 准备 Git 仓库

请参阅 编写 Dockerfile 的最佳实践。

初始化 Git (git init)，并为您的 git 仓库使用以下目录结构：

├── docker
|   ├── Dockerfile
├── document.tex

现在对于 docker/Dockerfile，我们将使用 harshjv/texlive-2015 Docker 镜像。此镜像包含 TeX Live 2015。

4.1. Dockerfile

FROM harshjv/texlive-2015
RUN tlmgr update --self --all

这将构建包含用于构建 TeX 文档的最新软件包的 Docker 镜像。

5. 添加您的 TeX 文档

将一些 TeX 文件添加到您的仓库。

6. 配置 Git 服务

对于 Webhooks/Services，我们需要按如下方式配置 Git 服务：

6.1. 对于 Bitbucket

目前无需配置。

6.2. 对于 GitHub

1. 转到您的仓库的Settings -> Webhooks & services -> Services
2. 选择 Travis CI

7. 配置持续集成服务

7.1. 对于 Semaphore

1. 进行初始提交并推送到远程分支（如果远程仓库为空），因为它至少需要一个远程分支。
2. 转到 SemaphoreCI
3. 添加新项目
4. 选择您的 Git 服务
5. 选择您的仓库
6. 选择分支（例如，master）

7. 选择您的帐户

完成这些初始步骤后，现在是配置构建和部署的时候了。

7.1.1. 设置线程

此设置脚本使用最新的 TeX 软件包构建 docker/Dockerfile，并获取 Dropbox Uploader 脚本。

sudo docker build -t texlive docker
curl "https://raw.githubusercontent.com/andreafabrizi/Dropbox-Uploader/master/dropbox_uploader.sh" -o dropbox_uploader.sh
chmod +x dropbox_uploader.sh

7.1.2. 构建线程

注意： 对于 master 分支中的 document.lex，document.pdf 将按如下方式上传：

Dropbox/[YOUR_APP_FOLDER]/master/document-latest.pdf
Dropbox/[YOUR_APP_FOLDER]/master/document-v[BUILD_NUMBER].pdf

此构建脚本编译 document.lex LeX 文档并构建 document.pdf PDF。然后，使用 Dropbox Uploader，版本化的 PDF 文件存储在分支的单独文件夹中。

sudo docker run -it -v ${SEMAPHORE_PROJECT_DIR}:/var/texlive texlive sh -c "pdflatex document.lex"
./dropbox_uploader.sh upload document.pdf ${BRANCH_NAME}/document-latest.pdf
./dropbox_uploader.sh upload document.pdf ${BRANCH_NAME}/document-v${SEMAPHORE_BUILD_NUMBER}.pdf

任何后续提交都将覆盖 document-latest.pdf 并创建一个新的 document-v[BUILD_NUMBER].pdf 文件。

7.1.3. 配置文件

1. 访问 Project Settings -> Configuration Files
2. 添加配置文件
3. 将 .dropbox_uploader 添加到文件路径
4. （可选）检查加密
5. 粘贴 ~/.dropbox_uploader 的内容
   • 在 MacOS X 中，pbcopy ~/.dropbox_uploader

7.2. 对于 Travis

设置过程和构建的脚本保持不变。将这些脚本放入单独的文件中，并创建一个 .travis.yml 文件。有关相关说明，请参阅这篇文章。

8. Git 提交和推送

现在是推送文档/更改的时候了。

git add .
git commit -m "Add some details"
git push origin master

9. 成功！

提示： 如果您只想在更改后共享最新的 PDF，请使用 URL 缩短服务（如 Bit.ly）在从 Dropbox 获取共享链接后指向此最新文档。

为什么？因为对于每个分支文件夹，[DOCUMENT_NAME]-latest.pdf 将始终包含最新的 PDF。

成功构建后，生成的 PDF 文件将在 Dropbox/[YOUR_APP_FOLDER]/master 文件夹中可用。