HAYASHI Kentaro
null+****@clear*****
Mon Aug 12 15:15:24 JST 2013
HAYASHI Kentaro 2013-08-12 15:15:24 +0900 (Mon, 12 Aug 2013) New Revision: 5f10bb1240f7d0d59be18691498e4d19d6f53139 https://github.com/groonga/groonga.org/commit/5f10bb1240f7d0d59be18691498e4d19d6f53139 Message: blog ja: about improving documentation about command reference Added files: ja/_posts/2013-08-12-reference-command-documentation.textile Added: ja/_posts/2013-08-12-reference-command-documentation.textile (+168 -0) 100644 =================================================================== --- /dev/null +++ ja/_posts/2013-08-12-reference-command-documentation.textile 2013-08-12 15:15:24 +0900 (74f5fd3) @@ -0,0 +1,168 @@ +--- +layout: post.ja +title: リファレンスコマンドのドキュメントをよいものにしていきませんか? +description: リファレンスコマンドのドキュメントをよいものにしていきませんか? +--- + +h2. リファレンスコマンドのドキュメントをよいものにしていきませんか? + +長い間懸案であった、groongaのAPIのドキュメント化については @whombx さんのおかげで一区切りつきました。そこで、次はリファレンスコマンドを整理する作業にとりかかりたいなぁと思っています。 + +ドキュメントを随時追加しているのですが、リファレンスマニュアルのコマンドについては、新旧のフォーマットが混在していて、統一されていないのが現在の課題となっています。 + +そこで、新しいフォーマットに統一する必要があるのですが、ここをお手伝いいただけると嬉しいです。 + +では具体的にどんなことをやればいいのかを説明します。基本的には関数ごとにpull requestを送ってもらうと進めやすいです。 + +あまり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:(あなたのGitHubのアカウント)/groonga.git +% cd groonga +% git remote add upstream git �� github.com:groonga/groonga +</pre> + +h4. ドキュメントビルド用の初期設定 + +ドキュメントを生成するために以下を実行します。 + +<pre> +% ./autogen.sh +% ./configure --enable-document +</pre> + +ここまでで、「最初にやること」は完了です。次は「作業ごとにやること」へと進みます。 + +h3. 作業ごとにやること + +以下では作業ごとにやることを説明します。 + +h4. groonga本家に追従する + +groonga本家の最新状態に追従して、作業がかぶらないようにします。 + +<pre> +% git fetch --all +% git checkout master +% git rebase upstream/master +</pre> + +最新の状態に追従できたら、「コマンドごとにやること」へと進みます。 + +h3. コマンドごとにやること + +以下では、例えば @cache_limit@ の作業をする場合で説明します。 + +h4. 作業用のブランチを作成 + +作業対象のブランチを作成します。 + +<pre> +% git checkout -b cache-limit +</pre> + +h4. 編集作業 + +ドキュメントの体裁を以下のように変更します。 + +旧: + +* 名前 +* 書式 +* 説明 +* 引数 +* 返値 +* 例 + +新: + +* Summary (名前のセクションから移動) +* Syntax (書式のセクションから移動) +* Parameters (引数のセクションから移動) +* Usage (例のセクションから移動) +* Return value (返値のセクションから移動) + +新しいほうのフォーマットに直してあるものは http://groonga.org/ja/docs/reference/command.html の一覧で見たときにコマンド名がボールド体で表記されます。 + +中には本文が英訳されていないものもありますが、英訳はしなくて構いません。 +新しいスタイルにドキュメントを更新するというのを機械的に行っていただければOKです! + +h4. ドキュメントの確認 + +マークアップに問題がないか、HTMLを確認します。HTMLを生成するには以下のコマンドを実行します。 + +<pre> +% cd doc/locale/en +% make html +</pre> + +いつも使っているブラウザで該当ファイルを確認して、移動した内容が追加されていればOKです。 + +<pre> +% firefox html/reference/commands/cache_limit.html +</pre> + + +h4. コミット + +HTMLに問題がないことを確認できたら、コミットします。 + +<pre> +% cd ${cloneしたディレクトリーのトップディレクトリー} +% git add doc/source/reference/commands/cache_limit.txt +% git commit +</pre> + +コミットするときのメッセージについては、例えば以下のようにします。 + +<pre> +doc: follow new markup guideline about cache_limit command documentation +</pre> + +h4. pushとpull request + +ご自分のリポジトリにpushして変更点をとりこめるように公開します。 + +<pre> +% git push -u origin cache-limit +</pre> + +ここで @cache_limit@ は前の方の作業で作ったブランチ名です。 + +ブラウザで https://github.com/(GitHubのアカウント)/groonga を開くと「 @cache-limit@ 」ブランチをpull requestする！みたいなUIができているので、そこのボタンを押してpull requestしてください。入力フォームがでてきますが、コミットしたときメッセージで十分なのでそのままpull requestしてOKです！ + +これで、ひととおりの作業は完了しました。 + +まだまだできるよ!という人は 「作業ごとにやること」の「groonga本家に追従」に戻って繰り返します。 + -------------- next part -------------- HTML����������������������������...다운로드
