概要
LaTeX での論文を Git で管理し、GitHub と継続的インテグレーション (CI) ツール を使って論文を pdf 化し、GitHub の Release ページから見られるようにすることで論文執筆を効率化する話（ただし、論文執筆速度が速くなっているかは別の話）。
これが実現したらもはや手元の環境には LaTeX 処理系はなくても論文執筆が可能なので、タイトルに「環境レス化」を入れた。手元に全く環境を持たないのは難しいとしても、複数の LaTeX 処理系を使い分けたりは格段にしやすくなる。
GitHub を使った論文執筆
論文を Git リポジトリで管理して、GitHub を用いて共著者間で共有している。主な活用法としては以下のような感じ。
- 研究テーマ単位でリポジトリを作る。論文は
papers/xxxみたいにディレクトリを掘って配置 - Issue 機能を使って執筆上の課題を明確化し、共著者間の議論の場を作る
- 議論に対応したコミットを Issue に結び付けることで議論が論文にどう反映されたか明確化
- 査読対応にも Issue 機能を活用
動機
ところが、共著者の中には論文を読んでチェックできればいい、という人がいる。そういう人にとっては、わざわざ論文 pull してコンパイルする作業が面倒だったりする。.latexmkrc を書いて latexmk main するだけにしても「pdf ファイルをメールで送ってください」となるのがオチだった。
ならば、GitHub に push したら CI で自動 pdf 化できるようにしたらいいのかな、と思ってやってみた。幸い、参考になるサイト（下記）があったので、大いに参考にした。
前提
- LaTeX 文書のコンパイルには TeXLive 環境を使う。
- LaTeX 文書のコンパイル支援には latexmk を使用、コンパイル手順は
.latexmkrcに記述し、リポジトリに含む - 論文のコンパイル対象は
main.texとする。 - 一つのリポジトリに複数の論文が含まれる。
papers/xxxなど、ディレクトリを掘って格納する - CI ツールには CircleCI を使用。論文のコンパイル（pdf化）を行う。どのディレクトリをコンパイルするかは CircleCI の設定で決定
現在のところ、CircleCI は無料で月間 1000 分ジョブを実行できる。LaTeX 文書の量によるが一度に必要な時間は２分程度。したがって、CircleCI を他の用途に使っていなければ月に 500 回くらいは論文をコンパイルできる計算になる。個人的な感覚としては十分な計算時間が利用できると思う。
目標とする動作
以下のような動作を目指す。特に、自動で pdf 化された論文が Release ページに登録されるのは使い勝手が良いと思う。これができるようになれば、手元の LaTeX 環境をセットアップしなくてもクラウド論文執筆が可能。（ただし、変更をリポジトリに push してからコンパイル結果が出力されるまでに２分かかる、ほとんどは Docker 環境の立ち上げに要する時間。）
- GitHub に論文の更新を push したときにコンパイルが通るかチェック
- GitHub に
X.X.X形式で tag を設定または更新したときに pdf ファイルを GitHub の Release としてアップロード
CircleCI の設定
今回は、CircleCI 2.0 を使う。必要な手順は以下の３つ。
GitHub リポジトリへの CircleCI 用設定ファイルの配置
CircleCI 2.0 では、.circleci/config.yml に YAML 形式の設定を記述する。以下の例は、 build, publish-github-release の２つのジョブからなっている。また、tag に応じた処理を行うために main ワークフローを設定している。このテストは teruo41/latex-circleci-test に置いてある。
[prism field=”circleci-latex-config” language=”YAML”]
build ジョブ内で papers/${TARGET_DIR} ディレクトリに移動して latexmk main を実行する。TeXLive を利用するための Docker イメージは Docker Hub の teruo41/ubuntu-texlive:latest を利用。Docker イメージについては後述。
publish-github-release ジョブはコンパイルした pdf ファイルを GitHub の Release ページに登録するためのジョブ。これには、cibuilds/github:0.10 の Docker イメージを利用。
複数のジョブ間で実行結果を受け渡すには、先行ジョブ（ここでは build）で persistent_to_workspace を指定する必要があり、後続ジョブ（ここでは publish-github-release）で attach_workspace を指定する必要がある。
main ワークフローは、X.X.X 形式のタグが GitHub 上で更新されたときに build と publish-github-release ジョブを実行する。これにより、tag に対応した pdf ファイルが GitHub の Release ページにアップロードされる。
Circle CI 用 Docker イメージの準備
動かせればよい人は、teruo41/ubuntu-texlive:latest の使用を推奨。これは、Ubuntu リポジトリに登録されている TeXLive をインストール済みの Docker イメージ。Ubuntu がサポートしているバージョンのそれぞれについてイメージを作る（予定）。
自前で環境を作りたい人は、Dockerfile を作って手元で docker build して Docker hub に push するか、GitHub か BitBucket に Dockerfile を格納したリポジトリを作って、Docker hub 上で Automated build するかどちらかで作ることができる。ちなみに、この例で使っているイメージは Automated build で作成している。それに使用している GitHub リポジトリは teruo41/ubuntu-texlive。
Circle CI 上での設定
以下の設定をする必要がある。
- Circle CI のアカウントを作成して GitHub アカウントに接続する
- Circle CI の環境変数を設定する。例の
.circleci/config.ymlで必要な変数は、GITHUB_TOKENとTARGET_DIRの２つ。
GITHUB_TOKEN は GitHub の Personal Access Token を設定する。リポジトリの Release ページに書き込むためには GitHub から適切な権限設定が必要。Public リポジトリか Private リポジトリかで必要な権限が変わる。詳しくはここを参照。
TARGET_DIR はコンパイルする論文のディレクトリを設定。papers/${TARGET_DIR} ディレクトリに移動した後 latexmk main が実行される。
テスト
ここまで設定したら使える状態のはず。論文のリポジトリを更新して push したらコンパイル可否がコミットページに表示される。また、tag を設定して push すれば、コンパイル結果の pdf ファイルが GitHub の Release ページに追加される。
tag を設定して GitHub に push する git コマンドの例。branch と同様に tag も push できる。
$ git tag -a 0.0.1 -m "Created tag 0.0.0" $ git push origin 0.0.1
一度設定した tag を更新するためには、-f オプションを使えばＯＫ。
$ git tag -af 0.0.1 -m "Updated tag 0.0.0" $ git push -f origin 0.0.1