老实说,这篇文章有点啰嗦,但我认为它可以帮助他人。如果您想知道如何使用 Travis CI 和 Minted 构建 LaTeX 文档,那么您来对地方了。

问题描述

如果您想知道我是如何想到这个困境的,我是一名博士生,我刚刚决定开始学习 LaTeX,因为它看起来很有用。然而,在这个过程中,我决定结合良好的软件工程原则,如版本控制和持续集成。事实证明,后者非常非常具有挑战性。

特别是,我一直在寻找一种使用 GitHub 中内置的 Travis CI 生成 LaTeX PDF 的方法。虽然这本身就是一个挑战,但我自己通过添加一个包 minted 来让事情变得更有趣,这需要一些外部依赖项。也就是说,我需要 Python 访问权限、Pygments 库和 shell 访问权限。事实证明,这比你想象的更具挑战性。

如何构建LaTeX

通常,我们可以使用任意数量的 LaTeX 工具来构建 LaTeX。对我来说,这意味着在我的 Windows 10 机器上下载 MikTex 和 Perl。之后,我下载了 Atom 的 LaTeX 插件,然后开始工作。

更正式地说,我使用以下步骤来设置用于 LateX 构建的 Windows 环境:

1.下载安装MikTex

2.下载安装草莓Perl

3.下载安装Python

4.下载安装Atom

5.下载安装latex包

6. 在 Latex 插件设置中勾选 Enable Shell Script

之后,您应该能够启动并运行。当然,我可能会在这里和那里缺少一些依赖项,因为我已经在我的系统上安装了其中的一些。

设置完所有依赖项后,构建工作流程如下所示:

1.编写并保存文档更改

2. 转到包 > LaTeX > 重建

3.利润

老实说,一旦安装了所有东西,这真的再简单不过了。毕竟,MikTex 会处理您缺少的软件包的安装,因此 LaTeX 依赖项应该不是问题。当然,在评论中让我知道。

如何自动化 LaTeX 构建

不幸的是,对于 Travis CI,上述方法是不切实际的。毕竟,我们希望能够在每次构建时使用命令行安装所有这些组件。

幸运的是,有一个 LaTeX 社区从事持续集成工作,因此已经有几种持续集成的方法。也就是说,尽管他们付出了很多努力,但我在起床和跑步时遇到了很多麻烦。如果你正在寻找世界上最悲伤的提交列表,查看我的拉取请求只是为了让构建工作。总共有大约 82 次提交,其中一半以上的构建失败。

当然,我不指望你会挖掘我的努力。相反,我想为您提供解决方案。

特拉维斯 YAML

对于每个 Travis CI 构建,您都需要一个 YAML 文件来告诉服务器如何构建您的代码。在这种情况下,我使用如下所示的 YAML:

language: generic
# Dependency of the minted package
before_install:
  - sudo apt-get install python-pygments
install:
  - source ./texlive/texlive_install.sh
cache:
  directories:
    - /tmp/texlive
    - $HOME/.texlive
# Change working directory so including files will work
before_script: cd $TRAVIS_BUILD_DIR/assignment01/doc/
script:
  - pdflatex --shell-escape ./assignment01.tex
deploy:
  provider: releases
  api_key:
    secure: ${GITHUB_TOKEN}
  file:
    - ./assignment01.pdf
  skip_cleanup: true
  on:
    tags: true
    branch: master
notifications:
  email: false

进入全屏模式 退出全屏模式

分解这一点,有几点需要注意。首先,重要的是要知道我们不能指定一种语言,因为 Travis CI 没有原生 LaTeX 构建支持。相反,我们必须使用通用设置:

language: generic

进入全屏模式 退出全屏模式

设置好语言后,我们可以先运行一个 before install 命令来获取 Python Pygments 包,该包有助于语法高亮显示:

before_install:
  - sudo apt-get install python-pygments

进入全屏模式 退出全屏模式

之后,我们在本地 shell 脚本上运行另一个安装命令——稍后会详细介绍:

install:
  - source ./texlive/texlive_install.sh

进入全屏模式 退出全屏模式

从那里,我们确保缓存我们的安装,所以我们不必每次构建都这样做:

cache:
  directories:
    - /tmp/texlive
    - $HOME/.texlive

进入全屏模式 退出全屏模式

初始设置后,我们进入工作目录,该目录恰好是我的 LaTeX 文件所在的文件夹。随意更改此行以满足您的需要:

before_script: cd $TRAVIS_BUILD_DIR/assignment01/doc/

进入全屏模式 退出全屏模式

现在我们在我们的工作目录中,我们可以安全地构建我们的 PDF。这是构建的真正魔力,因为我们需要一个特殊选项 -shell-escape,它允许我们访问我们的 python 包以进行语法高亮:

 script:
  - pdflatex --shell-escape ./assignment01.tex

进入全屏模式 退出全屏模式

在这一点上,其他一切都只是奖金。例如,我设置了 YAML 以将所有 PDF 部署到最新的标记版本。您需要使用自己的令牌填充 GITHUB_TOKEN。

deploy:
  provider: releases
  api_key:
    secure: ${GITHUB_TOKEN}
  file:
    - ./assignment01.pdf
  skip_cleanup: true
  on:
    tags: true
    branch: master

进入全屏模式 退出全屏模式

最后,我们关闭电子邮件通知,因为它们很烦人:

notifications:
  email: false

进入全屏模式 退出全屏模式

我们终于得到它了! Travis CI YAML 可以完成自动构建的工作。

其他构建脚本

除了这个 YAML,我们还需要一组用于设置 LaTeX 和我们需要的依赖项的脚本。幸运的是,我不必编写这些脚本,因为它们是我们的朋友在travis-ci-latex-pdf repo为我提供的。为了完整起见,我在下面分享了它们。确保将所有这些文件放在 repo 的根目录下名为 texlive 的目录下:

texlive/texlive.profile

selected_scheme scheme-basic
TEXDIR /tmp/texlive
TEXMFCONFIG ~/.texlive/texmf-config
TEXMFHOME ~/texmf
TEXMFLOCAL /tmp/texlive/texmf-local
TEXMFSYSCONFIG /tmp/texlive/texmf-config
TEXMFSYSVAR /tmp/texlive/texmf-var
TEXMFVAR ~/.texlive/texmf-var
option_doc 0
option_src 0

进入全屏模式 退出全屏模式

texlive/texlive_packages

xcolor
fancyhdr
fancyvrb
makecmds
multirow
chngcntr
fvextra
upquote
lineno
ifplatform
xstring
framed
caption
collection-fontsrecommended
minted
oberdiek
etoolbox
float
booktabs

进入全屏模式 退出全屏模式

texlive/texlive_install.sh

#!/usr/bin/env sh
# Originally from https://github.com/latex3/latex3
# This script is used for building LaTeX files using Travis
# A minimal current TL is installed adding only the packages that are
# required
# See if there is a cached version of TL available
export PATH=/tmp/texlive/bin/x86_64-linux:$PATH
if ! command -v texlua > /dev/null; then
  # Obtain TeX Live
  wget http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz
  tar -xzf install-tl-unx.tar.gz
  cd install-tl-20*
  # Install a minimal system
  ./install-tl --profile=../texlive/texlive.profile
  cd ..
fi
# Just including texlua so the cache check above works
tlmgr install luatex
# Install package to install packages automatically
tlmgr install texliveonfly
# Install babel languages manually, texliveonfly does't understand the babel error message
tlmgr install collection-langeuropean
# Common fonts with hard to debug errors if not found
#tlmgr install collection-fontsrecommended
# In the case you have to install packages manually, you can use an index of packages like
# http://ctan.mirrors.hoobly.com/systems/texlive/tlnet/archive/
# Or better, check https://www.ctan.org/pkg/some-package to see in which TeX Live package it is contained.
# Then you can add one package per line in the texlive_packages file
# We need to change the working directory before including a file
cd "$(dirname "${BASH_SOURCE[0]}")"
tlmgr install $(cat texlive_packages)
# Keep no backups (not required, simply makes cache bigger)
tlmgr option -- autobackup 0
# Update the TL install but add nothing new
tlmgr update --self --all --no-auto-install

进入全屏模式 退出全屏模式

瞧

此时,我们应该拥有使用 Travis CI 和 Minted 启动成功的远程 LaTeX 构建所需的一切。如果您有任何问题或疑问,请随时与我们联系。也就是说,Thomas Schouten 是真正的专家。我建议在某个时候访问他们的 repo,因为还有其他几种方法可以让事情正常进行。

无论如何,这就是我现在所拥有的一切。再次感谢你的来访!