PHP

PHPマニュアル日本語版ビルド用DockerイメージのCI環境、こんな感じでどうでしょうか

先日公開したPHPマニュアル日本語版ビルド用Dockerイメージ(iwamot/phd-ja)について、CircleCI でテストにパスした場合にだけ、イメージを Docker Hub にプッシュするようにしてみました。

ただ、なんでもかんでもプッシュするわけにはいかないので、下記のように処理させています。

master ブランチを GitHub リポジトリにプッシュした場合
CircleCI 上でイメージをビルドし、テストにパスした場合にだけ、latest イメージが Docker Hub にプッシュされます。
タグを GitHub リポジトリにプッシュした場合
CircleCI 上でイメージをビルドし、テストにパスした場合にだけ、同名タグ付きのイメージと latest イメージが Docker Hub にプッシュされます。
master 以外のブランチを GitHub リポジトリにプッシュした場合
CircleCI 上でイメージをビルドし、テストします。パスしても Docker Hub にはプッシュしません。
パスしなかった場合、そのブランチから master ブランチへのプルリクエストはマージできません(GitHub の「Branch protection rules」を利用)。

処理の詳細は .circleci/config.yml で定義されています。実装にあたっては「CircleCI2.0でDockerをビルドしてDocker HubにPushするまで」という記事がたいへん参考になりました。

なお、テストフェーズでは「ビルドされたマニュアルのトップページが参照できること」を確認しています。下記が該当部分です。

- run:
    name: Run test
    command: docker run --network container:phd-ja appropriate/curl --retry 10 --retry-connrefused http://localhost/phd-ja/

今回ご紹介したCI環境で今は満足していますが、改善すべき点があるかもしれません。何かお気づきの方は、お知らせいただければ幸いです。

Docker環境でPHPマニュアルの翻訳に参加してみませんか?

PHPマニュアルの日本語版をビルドするためのDockerイメージを公開しました。

このイメージを使うと、手間のかかる設定をせずに、PHPマニュアルの日本語翻訳が始められます。

翻訳の始め方

まずはオンラインエディタにログインし、翻訳対象ファイルを決め、翻訳を進めていきます。このあたりは以前Qiitaに書いた「PHPマニュアル日本語版にパッチを送る」が参考になるかと思います。

いい感じに翻訳できたら、表示を確認するため、Dockerコンテナ上でファイルを編集し、マニュアルをビルドしてみましょう。たとえば、ja/language/predefined/error/getcode.xml を編集する場合は下記のような手順になります。

# Dockerイメージを取得
docker pull iwamot/phd-ja

# コンテナを起動
docker run -it -p 8080:80 --name phd-ja iwamot/phd-ja

# 最新のソースを取得
docker exec phd-ja svn up

# コンテナのbashに入る
docker exec -it phd-ja bash

# ファイルを編集し、コンテナから抜ける
vi ja/language/predefined/error/getcode.xml
exit

# マニュアルをビルド
docker exec phd-ja ../scripts/phd-configure
docker exec phd-ja ../scripts/phd-build

編集内容は http://localhost:8080/phd-ja/error.getcode.html で確認できます。違和感がなければオンラインエディタに戻り、パッチを送ってみましょう。

イメージを公開した理由

PHPマニュアルのビルド環境を作るのには手間がかかります。PHP5環境の準備、Subversionリポジトリのチェックアウト、PhDのインストール、HTTPサーバの設定などが必要なためです。この手間を省ければ、翻訳への参加者が増えるかもしれないと考えました。

日本語への翻訳率は63%と比較的高いのですが、それでも現時点で4000ファイル以上が未翻訳、700ファイル以上が古くなっている状況です。翻訳率を高めるには、参加者を増やすのが効果的だと思っています。

改善案などの連絡手段

「Dockerfileのベストプラクティスはこうだよ」とか「テストがないけど、こんなふうに書いたらいいんじゃない?」とか「素のデザインだと見づらいのでCSSを書いてみたよ」とか、何かしらお気づきの点がありましたら、GitHubのプルリクエストやissue、Twitterなどでお知らせいただければ幸いです。

ぼくはこれまでサーバ上に直接、ビルド環境を作っていましたが、今後はこのDockerコンテナで作業します。不便を感じたら、随時改善して公開イメージに反映していきます。

PHPマニュアルの「導入」を「はじめに」に変えていただいた

変更前 (2017-09-02) 現在
「導入」リンクがある 「はじめに」リンクがある

変更を提案した理由

PHPのモジュールを追加する際、公式サイトのマニュアルを参照してサーバへの導入方法を確認することがよくある。

このとき、誤って「導入」リンクをたどってしまい、モジュールの説明しか確認できずに、がっかりすることもよくあった。

学ばないぼくも悪いのだが、そもそも「導入」なのが混乱の元なのではないだろうか。ためしにTwitterで検索してみると、同様の意見が見つかった。

ツイートにあるとおり、「導入」は「Introduction」の訳語であり、誤訳というわけではない。ただ、「サーバへの導入」という表現が日本語にはあるので、ほかの訳語をあてるのが適切だと考えた。


提案の流れ

とはいえ、ぼくの独断でマニュアルの表現を変えるわけにはいかない。「マニュアルについて」→「ドキュメントの改善を手助けするには」→「PHP Manual Contribution Guide」→「Joining the team」と読み進め、そこで推奨されているように、まずはメーリングリストで相談することにした。投稿したのが下記のメールだ。

2日ほど待ったが、とくにレスポンスはなかった。このときどう考えるかは人によるだろうが、ぼくは「反対者がいないのでチャンスだ」と受け止めた。パッチを作れば取り込んでもらえるかもしれない。


パッチ作成の準備

パッチを作るには、ソースファイルの変更箇所を理解する必要がある。また、変更後のマニュアルを実際に眺めてみて、違和感がないかどうかも確認すべきだ。

まずやるべきことは、ビルドツールであるPhDの入手だ。参考にしたのは、mumumuさんの「PHP manual generate HOWTO (version 2013-06-29)」だった。

試行錯誤の結果、ぼくの環境では下記のコマンドでPhDがインストールできた。

$ sudo yum install php-xml
$ sudo pear install doc.php.net/PhD doc.php.net/PhD_PHP doc.php.net/PhD_PEAR doc.php.net/PhD_IDE-1.1.1

続いて、ソースファイルを取得する。

$ svn co http://svn.php.net/repository/phpdoc/modules/doc-ja

変更箇所を理解するため、ソースをgrepする。

$ grep -rn '>導入' ./

「導入」を「はじめに」に変更後、ビルドしてみる。

$ php doc-base/configure.php --with-lang=ja --enable-xml-details
$ phd -d doc-base/.manual.xml -f xhtml -P PHP

ビルドされたマニュアルを確認し、違和感のないことが確認できた。


パッチの作成

ここまでくれば、オンラインのドキュメントエディタでパッチが作れる。ローカルで試したのと同じ要領でファイルを編集し、パッチを作った。

その後、メーリングリストにパッチのレビュー依頼メールを投稿した。


公式マニュアルへの適用

ほどなく、前述のmumumuさんから、svnにコミットした旨のリプライがあった。(ありがとうございます!)

そして本日、公式サイトのマニュアルに変更点が適用された。ちなみにこのマニュアルは毎日13時ごろ(日本時間)に更新されているようだ。


以上のような次第で、混乱せずにPHPマニュアルが読めるようになった。

余談だが、今回の件を通じて、未翻訳のファイルが3000以上あることを知った。今後はそちらの翻訳にも挑戦してみたい。

プロフィール
知識欲と謎解き欲が旺盛なWebエンジニア。AWS認定ソリューションアーキテクト - アソシエイト。JAPAN MENSA会員
記事検索