📚

GitHub Actions で論文 PDF を生成・配信する

2021/02/02に公開

Docker

これまでも GitHub のリポジトリを使って LaTeX ソースを管理し、共著の人を Collaborators に追加して一緒に論文を執筆している研究者の方は多かったと思います。

2021 年 1 月 21 日からは、 GitHub Pages を一般公開（GitHub Pages visibility: Public）だけでなく対象を制限して公開（GitHub Pages visibility: Private）できるようになりました。

つまり、共著者の Collaborators だけに PDF やデモ動画などのファイルを共有するのが簡単になりました！

この記事では、その方法と、関連する Tips を少し紹介します。なお、 LaTeX や GitHub Actions のソースコードは GitHub 上で、以下の URL で公開されています。

この内容は以下の Overleaf プロジェクトと同期されています。

前提: GitHub による論文 LaTeX ソースの管理

本題に入る前に、GitHub で論文のソースを管理するための前提を 2 点だけ共有します。

.gitignore でソース以外を無視

LaTeX を使った論文執筆では中間ファイルがいろいろと生成されるので、 .gitignore で無視する設定は必須です。自分の環境だと以下のようになっています。

.gitignore

*.synctex.gz
*.aux
*.bbl
*.blg
*.cut
*.dvi
*.fdb_latexmk
*.fls
*.log
*.pdf
*.out
*.xcp
*_temp.tex

Overleaf との連携

Overleaf はいわずと知れた Web ベースの LaTeX エディタですね。ローカルに LaTeX の執筆環境がない共著者がいる場合には、GitHub のリポジトリと Overleaf プロジェクトを連携しておくと便利です。

以前は GitHub と Overleaf 間の双方向の同期が難しかったように記憶しているのですが、今ではどちらの方向も 1 クリック（上のスクリーンショットで「Pull」「Push」と書いてあるボタン）で手軽にできるようになっています。

GitHub のリポジトリと Overleaf のプロジェクトはどちらが先に作られていても大丈夫です。この記事のリポジトリを fork する場合は、 fork した GitHub のリポジトリを Overleaf にインポート（Overleaf 内で New Project > Import from GitHub を選択）します。

準備: `latexmk` による論文 PDF 生成

まずはローカルに論文執筆環境を整える準備です。すでに latexmk が使える状態の場合は、このセクションの内容は飛ばしてください。

`latexmk` の使い方

自分が LaTeX を使い始めたころは latex ➡ bibtex ➡ latex ➡ dvipdfmx のようにコマンドを何回か走らせるバッチファイルを書いていた気がするのですが、今どきは latexmk というツールが便利のようです。

詳しくは Using Latexmk を見ると分かるのですが、カレントディレクトリの TeX ファイルをもとに PDF を生成するだけなら以下のコマンド一つで済みます。

latexmk -pdf

TeX ファイルを監視し、更新があるたびに PDF も生成し直すには -pvc オプションを使います。

latexmk -pvc

TeX Live のインストール

latexmk コマンドは、最新の TeX Live バンドルに含まれています。

TeX Live は各 OS 用のネットワークインストーラ install-tl を使ってインストールしてももちろんよいのですが、解説 Wiki によれば Windows では「基本的には ISO イメージを用いる方法をおすすめします」とのことです。

MacOS なら Homebrew で MacTeX をインストールするのが一般的なようです。

Docker イメージの利用

Docker が入っているマシンなら、 TeX Live を直接マシンにインストールするよりも、 TeX Live 導入済みの Docker イメージを pull して使うのが楽ですね。

docker pull arcatdmz/texlive

この Docker イメージは私が Docker Hub に push したもので、 aruneko さんの TeX Live Docker image に git コマンドといくつかの標準的なフォントを追加したものです。ソースコードは GitHub にあります。 1 GB 以上あるので、ネットワーク環境のいいところで pull しましょう。（git コマンドを追加した理由にはあとで触れます。）

カレントディレクトリの TeX ファイルをコンパイルするには以下のようにします。

docker run --rm -it -v $(pwd):/texsrc arcatdmz/texlive latexmk -pdf

PowerShell の場合は以下のようにします。

docker run --rm -it -v ${pwd}:/texsrc arcatdmz/texlive latexmk -pdf

GitHub Actions による論文 PDF の生成・配信

ローカルの執筆環境で latexmk -pdf のようにして論文 PDF を作成できるようになってさえいれば、あとは拍子抜けするほど簡単です。

論文 PDF の生成

基本的に、以下の内容の YAML ファイルを GitHub のリポジトリに置くだけです。

.github/workflows/gh-pages.yml

name: github-pages
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: github-pages
    if: "!contains(github.event.head_commit.message, 'skip ci')"
    runs-on: ubuntu-latest
    container: arcatdmz/texlive
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
      - name: Build PDF file
        run: latexmk -pdf && latexmk -c && mkdir -p docs && cp *.pdf ./docs/
      - name: Deploy pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

main ブランチに push されるたび、リポジトリのルートディレクトリで latexmk -pdf コマンドが実行され、生成された PDF ファイルが gh-pages ブランチにコミットされます。このコミット作業のために git コマンドが必要になるため、 TeX Live の Docker イメージに追加でインストールしています。

GitHub のリポジトリに論文 PDF 以外にも GitHub Pages で共有したいファイルがある場合、 cp *.pdf ./docs/ でコピーしている部分にそのファイルを追加するだけで GitHub Pages に公開されます。しっかり Git でバージョン管理されるので、内容に変更がない場合はコミットログも汚れません。

なお、 if 節の設定により、コミットメッセージに skip ci が含まれていればこの Action は実行されず、 PDF も生成されません。

生成された論文 PDF の配信

GitHub リポジトリの Settings > Options > GitHub Pages から gh-pages ブランチの / (root) ディレクトリを GitHub Pages として配信するように設定します。

GitHub Pages visibility を Private に設定した場合は次のような画面になります。

なお、こうしてアクセスできる人を GitHub リポジトリの Collaborators に制限してしまうと、GitHub にアカウントがない人はアクセスできなくなってしまいます。

そこで、 GitHub リポジトリは Private のまま、 GitHub Pages は Public にして、 PDF ファイルの名前を毎回ランダムに生成するという運用も考えられます。 GitHub Actions の最後に、生成された PDF ファイルへのリンクを Slack チャンネルに投稿するような Step を追加して周知するなど、やり方はいろいろとありそうです。

また、論文採択後などに全情報を公開してもよくなった場合は、プロジェクトのWebページを同じリポジトリの docs フォルダ内に置き、 GitHub リポジトリも Pages も Public にしてあげると便利そうです。

自動化で、研究をどんどん効率化していきましょう！

この記事を書く過程で Web 検索してみたら、ほかにも LaTeX を使った論文執筆を効率化している例がたくさん見つかりました。ぜひ参考にして、自分好みの自動化パイプラインを構築してみてください。

GitHub Actions ➡ GitHub Actions artifacts

main ブランチに push すると PDF をビルドして GitHub Actions の Artifact に保存
topic ブランチに push すると textlint や reviewdog で自動的に校正してくれる

GitHub PAT ➡ GitHub Pages

GitHub personal access token (PAT) を使って GitHub Pages に PDF ファイルを公開
index.html から PDF ファイルにリンクを張ってアクセスしやすくする
PAT の管理コストを考えないといけない

GitHub Actions ➡ GitHub Releases

GitHub Actions を使って GitHub Release に PDF ファイルを追加
独自 Docker イメージを毎回ビルドするので計算コストが高そう

GitHub Actions (pandoc) ➡ Git push

GitHub Actions を使って pandoc で Markdown を PDF 化
Git リポジトリの HEAD に作成した PDF ファイルを push

Circle CI ➡ GitHub Releases

Circle CI を使って GitHub Release に PDF ファイルを追加
GitHub Actions だと高度に自動化されている部分がマニュアルになっていて勉強になる？

Circle CI ➡ Amazon S3, Slack

Circle CI を使って PDF ビルドや aspell でのスペルチェックを行う
保存先は Amazon S3 で、成功した場合 Slack による通知も行う