Python 日本語ドキュメントのお引越し
Python ドキュメント日本語訳プロジェクトの翻訳者で管理者の cocoatomo です.
Note
Python ドキュメント日本語訳プロジェクトは, 常にあらゆる経路でのコントリビュートをお待ちしております. 「訳文の提出」のような直接的だけど労力のかかる貢献の他にも 「誤植報告」「読みづらい箇所を Twitter でつぶやく」 「読んだ感想を Twitter でつぶやく」などの方法があります.
翻訳をしたい方は Transifex から参加申請を, 誤植報告する方は GitHub の issue から issue 登録を, 何かしら Twitter でつぶやく人は @cocoatomo 宛てか, #pythondocja を付けてつぶやいてもらえると嬉しいです.
tl;dr
- 日本語ドキュメントが docs.python.org へお引越し
- 管理作業の自動化に成功
- Continuous Delivery の知見が増えた
経緯
Python を使っている人のほとんどは「Python の公式ドキュメント」と言われて思い当たる Web 上のドキュメントがあるはずです. それと意識していなくても検索してそのページに辿り着いた人もいるはずです.
「Python で分からないことがあって検索した」「Python のパッケージの使い方を知る」 「この Python の挙動が仕様なのか調べる」など色々な目的で閲覧され, Python を使った開発を少なからず支えています.
オリジナルの英語版が https://docs.python.org/3/ で公開されていて, それが日本語に翻訳されたものが https://docs.python.jp/3/ で公開されています. 日本語が母国語の人達なら, 英語に慣れないうちは日本語を読む方が10倍くらい速く内容を理解できると思います.
そんな日本語訳ドキュメントですが, 放っておいたら自然に生えてくるものではありません. 英語から日本語への変換は必ず人手が掛かっています. ただ, その人手は普段はあまり意識されない縁の下の存在です.
そんな状況で次のような出来事があり
Victor さんがさらに「翻訳を支援しようぜ」っていうメールを Python-Dev に投稿してくれ、多くの賛同のレスが得られました。 Victor さんマジイケメン。
(http://dsas.blog.klab.org/archives/2017-03/python-dev-201703.html より引用)
この提案から生まれた PEP 545 – Python Documentation Translations も無事受理されました.
3月号で紹介した、 Python 公式サイトで翻訳ドキュメントをホストする提案が受理されました。
PHP のドキュメントのように言語切替のUIが用意されて、より多くの人が母語に翻訳されたドキュメントにアクセスできるようにしていくことが目標です。
docs.python.jp で公開している日本語訳も、準備が整ったら docs.python.org に移管していくつもりです。
(http://dsas.blog.klab.org/archives/2017-05/python-dev-201705.html より引用)
そんな経緯で英語版だけでなく翻訳された Python ドキュメント (今のところ日本語とフランス語) も docs.python.org ドメインで公開されることとなりました. 今までの docs.python.jp での公開に不満は無いですが, それでもやはり docs.python.org ドメインで公開されると翻訳活動が評価されているんだと実感します.
課題
さてドキュメントサイトのお引越しも決まったところで残っている課題を片付けます.
これまでの運用では,
原文の更新を手作業で行っている
決まりきった作業とはいえ手作業はそれなりに煩雑な上, 作業者が手を動かせない状況になったらプロジェクトが止まる危険性がある
訳文の取得処理が VPS で動いている
何かあったときに作業者が VPS にログインする必要があり, ここでもプロジェクトが止まる危険性がある
という課題がありました.
管理している側からすると, プロジェクトの進行がたとえ管理者であったとしても個人に大きく依存するのは避けたいところです. 特に, プロジェクトが金銭的報酬ではなく個々人のやる気を原動力に動いているという, OSS プロジェクトによくあるパターンでは避けるべきことです.
そういった目的から, この2つの作業をマネージドサービスに乗せ, 人手を介さない Continuous Delivery の仕組みを構築する必要がありました.
Continuous Delivery を組んでみたよ
上記の課題の部分以外は Travis CI で自動化していて, その設定をした経験もあるので簡単に済むかと思いきや, 意外と引っ掛かるところがあったので知見を共有するために解説を書いてみます.
Travis CI or CircleCI
まずは Continuous Delivery (以下, CD) が実現できるサービスの選定です. プロジェクトの性質上, サービスは次に挙げる条件を満たしている必要があります.
設定ファイルをプロジェクトレポジトリで管理できること
管理者が変わっても同じ CD の仕組みを再構築できるように, 皆が見られるところに処理内容を記録しておきたい
GitHub に push するときに使用する秘密情報 (API Token, パスワードなど) を秘匿できること
サービスから自動で変更を push するときには API Token なりパスワードなどを使うのだが, これを上記の設定ファイルにそのまま書いてしまうと誰でも見れてしまうので, それは避けたい
定期実行の仕組みがあること
これまで cron で行っていた定期実行を実現する仕組みが必要
選択肢としたサービスは Travis CI と CircleCI です. これらのサービスを選んだ理由は, Travis CI は前述の通り使った経験があったため, CircleCI は cron 記法で定期実行のタイミングが設定できることを知っていたためです.
それぞれの観点で両者を比較すると次のようになりました.
設定ファイル
両サービスとも YAML 形式で記述する.
ただし Travis CI はシーケンスの要素1つにつき1コマンドしか書かけず, 複数コマンドを並べていくと読みづらくなる.
CircleCI はマッピングで書け, 縦棒 | (VERTICAL LINE, U+007C) の後に 複数個のコマンドを改行で区切りつつ書けるので読みやすい.
秘密情報の秘匿
Travis CI には秘匿のための仕組みが2つある. 1つ目は YAML ファイルの内容の一部を暗号化し, ビルド実行時に復号する仕組み, 2つ目は秘密情報を含むファイルを暗号化し, ビルド実行時に復号しビルド環境に配置する仕組み.
暗号化するために travis という Ruby 製のコマンドも用意されていて, gem コマンドでインストールできる.
CircleCI では, ジョブ定義の画面から秘匿情報を登録する.
両サービスを比較すると, Travis CI の方が手間が多いので CircleCI の方が便利.
定期実行
Travis CI では cron job という仕組みがあり, 日次 (daily), 週次 (weekly), 月次 (monthly) でジョブを実行できる. ただし実行する日次は指定できない.
CircleCI では workflow の設定項目の triggers/schedule/cron に cron 形式で細かく指定できる. */20 みたいな記法は使えないが, 列挙すれば良いのでそれほど困らない. Travis CI よりこっちの方が便利.
ここまでの比較だと CircleCI の方が良さそうですし, 実際 CircleCI にしようと思っていたのですが, 当初考慮から漏れていたこととしてビルドの時間制限がありました.
Travis CI はビルド1回につき50分の制限があるだけなのですが, CircleCI は月の合計時間に1500分 (25時間) の制限があります. 今まで VPS 上で行っていた訳文の取得処理が意外と時間がかかり, Python 2.7 と 3.6 の両方のジョブを1日に1回動かすだけで3000分になりそうだったので CircleCI は諦めて, Travis CI にしました. (有料プランにすれば上限は無くなるのですが, このプロジェクトにそんなお金があるはずもなく…….)
複数レポジトリ
CI サービスを普通に設定すると利用するレポジトリは1つだけになりますが, 訳文 (.po ファイル) を置くレポジトリには, 構成的な事情で訳文を生成したときに使った原文や訳文のテンプレート (.pot ファイル) は置けません. それなので, ジョブの中で「訳文を置くレポジトリ」と「原文や訳文テンプレートを置くレポジトリ」の2つを扱う必要があります.
.travis.yml を置いた方は Travis CI が git clone をしてくれるのですが, もう一方は当然何もしてくれないので, ジョブの中で git clone コマンドを実行しました.
CI ジョブの git push
ジョブの最後に更新された訳文, 原文と訳文テンプレートをそれぞれのレポジトリに push します.
ここでちょっとした落とし穴があって, 普通にコミットメッセージを書いて push すると, その push に CI サービスが反応し新たなジョブが起動する無限ジョブ地獄にはまります. もちろんそれを回避する方法はあって, コミットメッセージに [skip ci] や [ci skip] という文字列を含めると, そのコミットに対してはジョブが起動しません. この仕組みはどうやら複数の CI サービスで持っているので, 1つのレポジトリで複数の CI サービスを設定していてもお互いのジョブを起動し合うようなことはないみたいです.
もう1つ Travis CI で引っ掛かったことは, Travis CI が clone した後に HEAD のコミットハッシュで git checkout して detached head を作るところです.
これに気付かなかったため, 更新を push しても元のレポジトリに反映されませんでしたが, ジョブの中でブランチを checkout して commit 後 git push したら解決しました. おそらく不用意に元のレポジトリに push してしまわないように, こんな動作になっているんだと思います.
終わりに
長い文章になっちゃいましたが, ここまで読んでいただきありがとうございます.
翻訳プロジェクトを管理したことがある人や, その Continuous Delivery の仕組みを作ったことのある人ってかなり少数派だと思うので, 1つの事例として公開してみました. 細かいネタは色々あるのですが, 記事が長くなり過ぎるので端折って主要な話題についてだけ書きました.
飽くまで自分の趣味として続けている翻訳活動ですが, 感謝されることもちょいちょいあって, それはとても嬉しいです. これからも今までのように細々と続けていく予定です.
近々, 翻訳に PR で参加できる仕組みを作る予定なので, お楽しみに.