論文執筆を GitHub + 継続的インテグレーションで環境レス化する

概要

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 文書の量によるが一度に必要な時間は2分程度。したがって、CircleCI を他の用途に使っていなければ月に 500 回くらいは論文をコンパイルできる計算になる。個人的な感覚としては十分な計算時間が利用できると思う。

目標とする動作

以下のような動作を目指す。特に、自動で pdf 化された論文が Release ページに登録されるのは使い勝手が良いと思う。これができるようになれば、手元の LaTeX 環境をセットアップしなくてもクラウド論文執筆が可能。(ただし、変更をリポジトリに push してからコンパイル結果が出力されるまでに2分かかる、ほとんどは Docker 環境の立ち上げに要する時間。)

  • GitHub に論文の更新を push したときにコンパイルが通るかチェック
  • GitHub に X.X.X 形式で tag を設定または更新したときに pdf ファイルを GitHub の Release としてアップロード

CircleCI の設定

今回は、CircleCI 2.0 を使う。必要な手順は以下の3つ。

GitHub リポジトリへの CircleCI 用設定ファイルの配置

CircleCI 2.0 では、.circleci/config.yml に YAML 形式の設定を記述する。以下の例は、 build, publish-github-release の2つのジョブからなっている。また、tag に応じた処理を行うために main ワークフローを設定している。このテストは teruo41/latex-circleci-test に置いてある。

version: 2

executors:
  my-executor:
    working_directory: /root

jobs:
  build:
    docker:
      - image: teruo41/ubuntu-texlive:latest
    steps:
      - checkout
      - run:
          command: |
            cd papers/${TARGET_DIR}
            latexmk main
      - persist_to_workspace:
          root: /root
          paths:
            - project
  publish-github-release:
    docker:
      - image: cibuilds/github:0.10
    steps:
      - attach_workspace:
          at: /root
      - run:
          name: "Publish Release on GitHub"
          command: |
            cd /root/project/papers/${TARGET_DIR}
            ghr -t ${GITHUB_TOKEN} -u ${CIRCLE_PROJECT_USERNAME} -r ${CIRCLE_PROJECT_REPONAME} -c ${CIRCLE_SHA1} -delete ${CIRCLE_TAG} main.pdf

workflows:
  version: 2
  main:
    jobs:
      - build:
          filters:
            tags:
              only: /^\d+\.\d+\.\d+$/
      - publish-github-release:
          requires:
            - build
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^\d+\.\d+\.\d+$/

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 上で更新されたときに buildpublish-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_TOKENTARGET_DIR の2つ。

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 オプションを使えばOK。

$ git tag -af 0.0.1 -m "Updated tag 0.0.0"
$ git push -f origin 0.0.1

参考

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください