zoukankan      html  css  js  c++  java
  • [Latex]Travis-CI与Latex构建开源中文PDF

    博主有一本开源书籍,用 latex 排版,托管在Github上。但用 latex 不像是 Markdown,当tex文本更新时,用于最终浏览的PDF文件很难得到及时的更新, 所以博主一直想找到一套工具,实现以下两点愿望:

    • 自动构建以测试是否可以成功编译生成PDF文件。
    • 始终都能有一个最新版的PDF版本可供下载。

    博主之前曾使用过Travis-CI进行单元测试的自动运行,所以猜测它能够实现博主的小心愿。最后一探索,果然可以,但网上相关的中文资料较少,遂自己摸索写下这一篇博客。主要的资料来源于Travis-CI官方文档

    自动构建第一步,安装latex环境

    由于Travis-CI不再对 public repository 提供 Caching Dependencies , 所以我们针对 latex 的每次自动构建都需要下载texlive-full包。不过博主发现,在配置好后,自动构建的时间一般在 8 分钟左右,时间还是相当可以的。

    首先创建一个.travis.yml文件,在文件中填入以下两行

    sudo: required
    dist: trusty
    

    其中 dist: trusty是指定ubuntu版本为14.04

    为了能够成功编译中文PDF,我们可以使用xelatex。在这里博主直接下载了texlive-full包环境用于编译。所以我们在.travis.yml文件中加入环境配置的代码:

    before_install:
    - sudo apt-get update
    - sudo apt-get -y install texlive-full
    

    由于在服务器端一个中文字体都没有,博主建议开源书籍可以有一个fonts目录用于存放编译所用字体。如果在 ubuntu 下使用 xelatex ,默认字体是 Adobe的四款开源字体。接下来我们将仓库里的字体安装在服务器的环境下。Linux系统中安装字体很简单,将字体文件只需要放在usr/share/fonts文件目录下即可。这里有个小坑在于,服务器上没有usr/share/fonts目录,需要自己新建一个。博主安装字体的代码如下,opentype目录表示.otf格式字体。:

    - sudo mkdir -p /usr/share/fonts/opentype/
    - sudo mv ./guide-book/fonts/AdobeFangsongStd-Regular.otf /usr/share/fonts/opentype/
    - sudo mv ./guide-book/fonts/AdobeHeitiStd-Regular (v5.010).otf /usr/share/fonts/opentype/
    - sudo mv ./guide-book/fonts/AdobeKaitiStd-Regular (v5.010).otf /usr/share/fonts/opentype/
    - sudo mv ./guide-book/fonts/AdobeSongStd-Light (v5.010).otf /usr/share/fonts/opentype/
    - sudo mkfontscale
    - sudo mkfontdir
    - sudo fc-cache -fv
    

    括号需要进行转义,并且需要使用sudo fc-cache -fv对字体列表进行更新。

    如果在编译latex时出现The font "Adobe Song Std" cannot be found.,可以在 .travis.yml 中加入fc-list :lang=zh打印字体信息以进行 debug 。

    自动构建第二步,编译生成PDF

    在安装完 latex 环境后,我们接下来就可以使用xelatex进行编译了。
    一般对于 latex 稍微熟悉一些的朋友应该都没有问题。将编译的指令写在scripts:下即可自动运行。

    现在博主的.travis.yml长这样:

    sudo: required
    dist: trusty
    before_install:
    - sudo apt-get update
    ...
    - sudo fc-cache -fv
    script:
    - cd guide-book
    - make
    

    在这里博主有两个小建议:

    1. latex 使用 nonstopmode模式。在编译时,如果不加任何选项,出错时latex会等待用户输入一个新的tex文件名进行重新编译。但是自动构建并没有人帮我们输入,所以在前期摸索试错时,如果加上这个编译选项,可以更快地看到自动构建的结果,否则就需要等待较长时间(这时候是超时错误)。使用的方法如下:
    xelatex SAMPLE.tex -interaction=nonstopmode
    
    1. 可以写个 Makefile 文件,只需要 make 即可一步编译。博主就将 xelatex 执行的脚本写在了 Makefile 文件中。

    自动构建第三步,PDF自动上传到Github

    我们已经生成了PDF文件,下面我们来一步一步把它上传到Github上。

    首先,执行sudo gem install travis安装travis.

    如果没有gem的话,首先需要安装gem,安装方法请自行寻找。

    如果在安装travis时失败了,可能是因为网络原因。博主推荐使用ruby淘宝源,淘宝源已经不再支持http,之前配置成http的朋友记得更换。如果是第一次配置,使用gem sources -a https://ruby.taobao.org/ --remove http://rubygems.org/即可替换源。

    安装信息如下:

    Fetching: ethon-0.8.1.gem (100%)
    Successfully installed ethon-0.8.1
    Fetching: typhoeus-0.8.0.gem (100%)
    Successfully installed typhoeus-0.8.0
    Fetching: travis-1.8.2.gem (100%)
    Successfully installed travis-1.8.2
    Parsing documentation for ethon-0.8.1
    Installing ri documentation for ethon-0.8.1
    Parsing documentation for typhoeus-0.8.0
    Installing ri documentation for typhoeus-0.8.0
    Parsing documentation for travis-1.8.2
    Installing ri documentation for travis-1.8.2
    Done installing documentation for ethon, typhoeus, travis after 10 seconds
    3 gems installed
    

    在成功下载了travis后,我们首先要登录,进入你要自动构建的git 仓库目录下,使用sudo travis login --auto进行登录。

    qian@thinkpad:~/BUAAOS-guide-book# sudo travis login --auto
    We need your GitHub login to identify you.
    This information will not be sent to Travis CI, only to api.github.com.
    The password will not be displayed.
    
    Try running with --github-token or --auto if you don't want to enter your password anyway.
    
    Username: SivilTaram 
    Password for SivilTaram: ****************
    Successfully logged in as SivilTaram!
    

    博主在这里一开始遇到了坑。在windows下使用cmd,在输入密码时都显示明文密码,并且回车后无响应,如果有朋友知道解决方法或者原因,烦请赐教。最后博主用ubuntu,在shell里成功登录。

    登录后,我们来使用travis setup releases来指定要上传的文件

     sudo travis setup releases
    [sudo] password for qian: 
    Detected repository as SivilTaram/BUAAOS-guide-book, is this correct? |yes| yes
    Username: SivilTaram
    Password for SivilTaram: ***************
    File to Upload: guide-book/guide-book.pdf
    Deploy only from SivilTaram/BUAAOS-guide-book? |yes| yes
    Encrypt API key? |yes| yes
    

    其中Encrypt API key是用于加密的,建议选择 yes。
    在完成这一步后,我们可以发现我们的.travis.yml文件中多了几行,博主的文件增加内容如下:

    deploy:
      provider: releases
      api_key:
        secure: xxxxxxxx
      file: guide-book/guide-book.pdf
      on:
        repo: SivilTaram/BUAAOS-guide-book
    

    但是注意,deploy 设置还没有结束!根据官方文档,Travis-CI会在script执行结束后,默认清除所有生成的文件,所以一定要加上一句skip_cleanup: true。现在我们完整的.travis.yml文件应该类似于下面的结构:

    sudo: required
    dist: trusty
    before_install:
    - sudo apt-get update
    - sudo apt-get -y install texlive-full
    - sudo tex -v
    script:
    - cd guide-book
    - make
    deploy:
      provider: releases
      api_key:
        secure: xxxxx
      file: guide-book/guide-book.pdf
      skip_cleanup: true
      on:
        repo: SivilTaram/BUAAOS-guide-book
    

    如果想添加多个上传文件,将 file: 的选项更改成:

    file:
        - "FILE 1"
        - "FILE 2"
    

    当我们在某次 commit 时已经预先知道本次 commit 无法通过编译,不想自动构建时,可以使用git commit -m "[ci skip] xxxx"跳过自动构建。

    如果想触发自动构建并上传的话,需要打tag,如果不打tag,在realese里的名字会很难看。打的tag将成为最新版本的名字。可以按照如下步骤进行push。注意commit中不要使用[ci skip]

    git tag -a v1.1.1 -m "tags content"
    git push --tags
    git push
    

    其中 v1.1.1即版本号

    如果自动构建成功的话,你将在仓库的releases中看到刚刚自动构建的成果,比如博主的仓库

    如果有遗漏与错误之处还望各位指出~

  • 相关阅读:
    康复计划
    Leetcode 08.02 迷路的机器人 缓存加回溯
    Leetcode 38 外观数列
    Leetcode 801 使序列递增的最小交换次数
    Leetcode 1143 最长公共子序列
    Leetcode 11 盛水最多的容器 贪心算法
    Leetcode 1186 删除一次得到子数组最大和
    Leetcode 300 最长上升子序列
    Leetcode95 不同的二叉搜索树II 精致的分治
    Leetcode 1367 二叉树中的列表 DFS
  • 原文地址:https://www.cnblogs.com/SivilTaram/p/travis-ci_latex_auto-build_github.html
Copyright © 2011-2022 走看看