📚

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

7 min read

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

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

https://github.blog/changelog/2021-01-21-access-control-for-github-pages/

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

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

https://github.com/arcatdmz/acm2021-primary-article-template/

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

https://www.overleaf.com/read/mwfwdmcrwnrv

前提: 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 プロジェクトを連携しておくと便利です。

Gyazo

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

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

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

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

latexmk の使い方

自分が LaTeX を使い始めたころは latexbibtexlatexdvipdfmx のようにコマンドを何回か走らせるバッチファイルを書いていた気がするのですが、今どきは 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 イメージの利用

https://twitter.com/arcatdmz/status/1356041067515133955

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

docker pull arcatdmz/texlive

この Docker イメージは 私が Docker Hub に push したもの で、 aruneko さんの TeX Live Docker imagegit コマンドといくつかの標準的なフォントを追加したものです。ソースコードは 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 visibilityPrivate に設定した場合は次のような画面になります。

Gyazo

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

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

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

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

Related Work

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

GitHub Actions ➡ GitHub Actions artifacts

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

Gyazo

https://poyo.hatenablog.jp/entry/2020/12/05/110000

GitHub PAT ➡ GitHub Pages

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

http://raven38.hatenablog.com/entry/2019/11/08/000328

GitHub Actions ➡ GitHub Releases

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

https://qiita.com/takuseno/items/2b4c4a129205d03526ad

GitHub Actions (pandoc) ➡ Git push

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

https://mat2.net/posts/2020/01/09/github-actions-with-pandoc.html

Circle CI ➡ GitHub Releases

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

https://www8281uo.sakura.ne.jp/blog/?p=666

Circle CI ➡ Amazon S3, Slack

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

https://blog.ymyzk.com/2017/12/ci-for-writing-papers/

Discussion

ログインするとコメントできます