ドキュメントを作りたくなってしまう魔法のツールとしてSphinxがあります。 全文検索エンジンGroongaでは、Sphinxを英語と日本語のドキュメントの生成に利用しています。
しかし、バージョン管理する上でいくつか課題がありました。そのあたりの事情に触れた、gettextとバージョン管理システムの相性の悪さを解消する案という記事があります。1
今回はそのときの案を引用しつつ、実際どのように解決したのかをGroongaの例で紹介します。2
どう相性が悪いのか？
当時の記事では相性の悪さとして次の点をあげていました。
- バージョン管理対象の.poファイルに出現位置情報が含まれているため、出現位置情報もバージョン管理せざるを得ない
- 出現位置情報もバージョン管理するとノイズが大きい
上記を解決する案として以下を紹介しました。
- バージョン管理しない作業用の.poファイルを導入する
- 作業用の.poファイルには出現位置情報を入れるため翻訳時の利便性は維持
- 作業用の.poファイルから出現位置情報を抜いた.poファイルを作り、それをバージョン管理対象とする
Groongaのドキュメントでpoファイルを更新するときには変更行が2000行くらいで、しかもその大部分がドキュメントにおける出現位置情報だったので、このやりかたで一見すべてうまくいくように思えました。
しかし、それでもまだノイズが残っていることに気づきました。
# 161fad58cef448c698df3d188d57135d
msgid "13.10 Saucy Salamander"
msgstr ""
上記の 161fad58cef448c698df3d188d57135d ですが、これはSphinxが生成する uuid です。
メッセージの出現位置情報については、GNU gettextでは --no-location オプションがあるので除去できます。しかし uuid についてはSphinxが独自に生成しているためどうすることもできません。
どう解決したのか？
生成されたpoから uuid を除去する仕組みをGroongaのドキュメント生成に組みこむことも考えましたが、やはりSphinx本体で uuid を生成しないという選択肢が選べるならそれにこしたことはありません。Groonga特有の問題ではなく、広く一般に使えるものだからです。
そこで Sphinx自体を修正し uuid の出力を制御可能にするオプションを追加しました。この変更はすでに Sphinx本体にとりこんで もらいました。
Sphinx 1.3b1以降で使えるようになります。
uuidを無効にするには
Sphinx 本体にとりこんでもらった時点では、従来との互換性から uuid の生成をデフォルトでは有効なままにしていました。
しかし、その後 デフォルトで出力しないように既定値がFalseへと変更されたようです。そのため、何もしなくても以下のように config.py に書いたのと同じことになります。
#source python
gettext_uuid=False
まとめ
今回はGNU gettextとバージョン管理の相性の悪さを、Sphinx本体を修正することで解決した事例を紹介しました。 使っているフリーソフトウェアの「こうだったらもっといいのに」があれば、開発元にフィードバックして、なおしてもらえるといいですよね。
