HAYASHI Kentaro
null+****@clear*****
Mon Jul 29 14:23:55 JST 2013
HAYASHI Kentaro 2013-07-29 14:23:55 +0900 (Mon, 29 Jul 2013) New Revision: 76b5bb7ed0cdda308b5e3943dbdbdc37be4c3a57 https://github.com/groonga/groonga.org/commit/76b5bb7ed0cdda308b5e3943dbdbdc37be4c3a57 Message: blog: update API documentation entry Make it clear what to do, and what not to do. See also [groonga-dev,01551] Reported by @whombx. Thanks!!! Modified files: ja/_posts/2013-07-22-api-documentation.textile Modified: ja/_posts/2013-07-22-api-documentation.textile (+104 -18) =================================================================== --- ja/_posts/2013-07-22-api-documentation.textile 2013-07-29 10:19:21 +0900 (dad82e8) +++ ja/_posts/2013-07-22-api-documentation.textile 2013-07-29 14:23:55 +0900 (99585e4) @@ -20,51 +20,137 @@ h2. APIドキュメント化始めました では具体的にどんなことをやればいいのかを説明します。基本的には関数ごとにpull requestを送ってもらうと進めやすいです。 -1. groongaとgroonga.orgのリポジトリをcloneして以下のコマンドを実行します。 +あまりGitHubでの作業に慣れていなくてもできるように、「最初にやること」と「作業ごとにやること」、「関数ごとにやること」に分けて順に説明します。 + +* 最初にやること +* 作業ごとにやること +* 関数ごとにやること + +h3. 最初にやること + +以下では、最初に一度だけ実施しておけば良いことを説明します。 + +h4. 最初の設定 + +まずは、gitの設定をしましょう。すでにある程度gitを使っている場合には初期設定はすでに完了しているかも知れません。その場合には飛ばして構いません。 + +<pre> +% git config --global user.name "あなたのユーザー名" +% git config --global user.email "あなたのメールアドレス" +</pre> + +上記はコミットログに使われます。公開しても差し支えないユーザ名もしくはメールアドレスを設定します。 + +h4. GitHubでforkする + +GitHubにアカウントがなければ用意してください。アカウントが用意できたら、ログインした状態で以下のURLにアクセスします。 + +* "groongaリポジトリをforkする":https://github.com/groonga/groonga/fork + +リポジトリ選択画面でご自分のリポジトリへとforkしてください。 + +h4. 作業用リポジトリの初期設定 + +次は作業用にforkしたリポジトリを手元にcloneします。このとき、本家の変更に追従するための設定を行います。 <pre> -% git clone git://github.com/groonga/groonga.git -% git clone git://github.com/groonga/groonga.org.git +% git clone git �� github.com:(あなたのGitHubのアカウント)/groonga.git % cd groonga +% git remote add upstream git �� github.com:groonga/groonga +</pre> + +h4. ドキュメントビルド用の初期設定 + +ドキュメントを生成するために以下を実行します。 + +<pre> % ./autogen.sh -% ./configure --enable-document --with-groonga-org-path=(groonga.orgをcloneしたパス) +% ./configure --enable-document +</pre> + +ここまでで、「最初にやること」は完了です。次は「作業ごとにやること」へと進みます。 + +h3. 作業ごとにやること + +以下では作業ごとにやることを説明します。 + +h4. groonga本家に追従する + +groonga本家の最新状態に追従して、作業がかぶらないようにします。 + +<pre> +% git fetch --all +% git checkout master +% git rebase upstream/master </pre> -2. include/groonga.hを眺めて日本語のコメントがついている関数を一つ探します。例:grn_ctx_open +最新の状態に追従できたら、「関数ごとにやること」へと進みます。 -3. 関数が見つかったら、関数に対応するブランチをつくります。 +h3. 関数ごとにやること + +以下では、例えば @grn_ctx_open()@ の作業をする場合で説明します。 + +h4. 作業用のブランチを作成 + +作業対象のブランチを作成します。 <pre> % git checkout -b grn-ctx-open </pre> -4. 関数のコメントの内容をdoc/source/reference/api/grn_ctx.txtに移動します。移動するときに英訳とマークアップを行います。grn_ctx.txtにはすでにgtn_ctx_initの例があるのでそれを真似して下さい。 +h4. 編集作業 + + �� include/groonga.h@ から @doc/source/reference/api/grn_ctx.txt@ にドキュメントを移動します。 + +中には英訳されていないものもありますが、英訳はしなくて構いません。 +移動先のドキュメントのフォーマット化を機械的に行っていただければOKです! + +h4. ドキュメントの確認 + +マークアップに問題がないか、HTMLを確認します。HTMLを生成するには以下のコマンドを実行します。 + +<pre> +% cd doc/locale/en +% make html +</pre> + +いつも使っているブラウザで該当ファイルを確認して、移動した内容が追加されていればOKです。 + +<pre> +% firefox html/reference/api/grn_ctx.html +</pre> -5. groonga.hからはコメントを削除します。 -6. 対象となるファイルを更新するために以下を実行します。 +h4. コミット + +HTMLに問題がないことを確認できたら、コミットします。 <pre> -% make update-files +% cd ${cloneしたディレクトリーのトップディレクトリー} +% git add include/groonga.h +% git add doc/source/reference/api/grn_ctx.txt +% git commit </pre> -7. メッセージカタログを更新するために以下を実行します。 +コミットするときのメッセージについては、例えば以下のようにします。 <pre> -% make update-po +doc: move grn_ctx_open() document to Sphinx text from header file </pre> -8. ドキュメントを生成するために以下を実行します。 +h4. pushとpull request + +ご自分のリポジトリにpushして変更点をとりこめるように公開します。 <pre> -% make update-document +% git push -u origin grn-ctx-open </pre> -9. ドキュメントの生成結果を見て翻訳されていない部分を修正します。doc/locale/ja/LC_MESSAGES/po以下のメッセージカタログのmsgstrを修正することになります。 +ここで @grn-ctx-open@ は前の方の作業で作ったブランチ名です。 -10. 英語のドキュメントと日本語のドキュメントがきちんと生成できたらコミットしておきます。 +ブラウザで https://github.com/(GitHubのアカウント)/groonga を開くと「 @grn-ctx-open@ 」ブランチをpull requestする！みたいなUIができているので、そこのボタンを押してpull requestしてください。入力フォームがでてきますが、コミットしたときメッセージで十分なのでそのままpull requestしてOKです！ -11. 完成です。pull requestを送りましょう。 +これで、ひととおりの作業は完了しました。 -HTMLの結果を確認するにはdoc/locale/en/htmlもしくはdoc/locale/ja/html以下を参照してください。 +まだまだできるよ!という人は 「作業ごとにやること」の「groonga本家に追従」に戻って繰り返します。 -------------- next part -------------- HTML����������������������������...Download