概要

Groongaを使ってて、必要な情報がマニュアルに載ってない事があったりしませんか。もしくは部分的に英語で気持ち悪かったり。
そんな時、OSSであるGroongaでは自分でドキュメントを直すことでプロジェクトに貢献できます。

この記事ではMacOSXでGroongaのドキュメントを更新する環境を整える方法と、実際にドキュメントを直してサイトに取り込まれる前までを説明します。

なお、偉そうに「説明します」と言っていますが、実は筆者にとっても初めての作業なので、この記事は体験談に近い内容です。
そのため、特に環境構築周りで無駄な手順を踏んでいる可能性があります。
もし、もっといいやり方を知ってる人がいたら、ぜひアドバイスください。

前提条件

Macにbrewとpip、automake、libtoolがインストールされていること。
- 環境を整えるのに使います。
Githubのアカウントを持っていること。
- GroongaのドキュメントはGithubで管理されているので、ドキュメントへの貢献はpull request(以下、PR)で行なわれます。
- Git/GitHubの操作については今回は詳しく説明しません。
ある程度、英語の読み書きができること。
- 一番のハードルかもしれません。
- Groongaのドキュメントは英語と日本語を同時に更新する必要があるため(後述)、若干の英語力は必要です。
- 書くのは厳しいけどある程度読めるという方は、既に英語だけあるドキュメントを和訳するところから始めるといいのかもしれません。

ドキュメントを更新する環境を整える

Groongaのドキュメントを更新するためには、Sphinxとgettextというソフトウェアを使います。
これらのインストール手順については、公式ドキュメントの手順に載っていますが、一部状況が変わっていて、現在ではSphinxを手動でインストールする必要があります。

それを反映すると、手順は以下の通りです。

$ brew install gettext
$ echo PATH="`brew --prefix gettext`/bin:\$PATH" >> ~/.zshrc
$ source ~/.zshrc

$ brew install python
$ sudo pip install sphinx

GitHub上でforkして、clone

Groongaのドキュメントの原稿はGitHubのGroongaのリポジトリ内にあるため、まずはGitHub上でこのリポジトリをforkした上で、Mac上にcloneしてきます。
(具体的な手順については、今回は割愛します)

ドキュメントを更新できるようにconfigureする。

$ cd groonga # cloneしてきたディレクトリ
$ ./autogen.sh
$ ./configure --enable-document

ここまでで環境の整備は完了です。
今後はこのcloneしてきたリポジトリに対して修正していきます。

ドキュメントの記述

GroongaのドキュメントはSphinxの国際化機能を使ってます。
これが多少ややこしく、以下の流れでドキュメントを書いていく事になります。

英語で書いた原稿に対して、英語のpoファイルを作成するのが若干手間ですが、基本的にはコマンド1個で済むのでめげずに頑張ります。

ブランチを切る

まずは通常のPRを送る時のようにブランチを切って、本家に追従しておきます。

$ git checkout -b update-contribution-documentation-introduction-ja
$ git pull upstream master

なお今回のブランチ名は、単純にupdate-対象ページのURL-言語としました。

英語で元原稿を書く

前述の通り、まずは英語で原稿を書きます。

原稿となるファイルは、doc/source以下にテキストデータで置いてあります。
開くと分かりますが、中身はReStructuredTextフォーマットで書かれていて、ファイル名はURLと対応しているようです。

# このファイルがhttp://groonga.org/ja/docs/contribution/documentation/introduction.html の元ファイルです。
$ vim doc/source/contribution/documentation/introduction.rst   # 編集
$ git add doc/source/contribution/documentation/introduction.rst
$ git commit -m "doc: add xxxx."

ちなみに、コミット時のコメントにはdoc:とつけるのがルールっぽいです。

日本語版を作成

英語の元原稿が書けたら、今度はそれを和訳します。
まずは以下のコマンドを実行して、英語/日本語の対応表であるpoファイルを作ります。

$ cd doc/locale/ja/LC_MESSAGES
$ make update
$ vim contribution.po   # 作られた対応表
$ git add contribution.po
$ git commit -m "doc ja: add xxxx."

ファイルを開くと、msgidに英語、msgstrに日本語が書かれているのがわかるかと思います。
この中から自分の書いた英語を探すとmsgstrの部分が空欄になっているので、そこを埋めていけばOKです。
なお、msgstrが空欄でない場合は、同じ表現が既に別の場所で使われているという事ですので、その部分を参照しながら慎重に対応してください。

英語版を作成

日本語版と同じように英語用のpoファイルを作成します。

$ cd doc/locale/en/LC_MESSAGES
$ make update
$ vim contribution.po   # 作られた対応表
$ git add contribution.po
$ git commit -m "doc en: add xxxx."

なお、英語版のpoファイル内のmsgstrの部分は、基本的には空欄のままで良さそうです。

確認方法

POファイルを書いた後、実際のHTMLでの見栄えを確認できます。
以下のコマンドで、rstファイルとpoファイルからHTMLが生成されるので、確認してください。

日本語版の場合

$ cd doc/locale/ja
$ make html
$ open html/contribution/documentation/introduction.html

コミット & プルリクエスト

ここまでで作業は完了。
作成した、rstファイルとpoファイルをコミットして、後は通常どおり、GitHubのサイトからPRを飛ばしましょう。
マージされたら、次回リリース時にサイトに反映されるはずです。

以上です。お疲れ様でした。

ちなみに今回の練習では、前述のSphinxのインストール手順が誤っている部分を修正してみました。ご参考まで。

参考、あるいは、より丁寧な説明

今回、Groongaのドキュメントを実際に直すにあたって、公式ドキュメント意外に以下のページを参考にしました。