Tutorial.textile

私もリファレンスを書いてみたいわ！という方のためのチュートリアルです。このエントリは定期的に見直されるべきです。

1. doctree リポジトリの準備

GitHub アカウントをまだ持っていなければサインアップします。ログイン後に https://github.com/rurema/doctree リポジトリを fork します。 fork した自分のリポジトリを clone します。

$ git clone git@github.com:[YOUR_NAME]/doctree.git

doctree というディレクトリができるので cd し、以下のコマンドを実行します。 bundle コマンドが使えない場合は先に gem install bundler を実行してください。

$ bundle install
$ bundle exec rake

実行すると /tmp 以下に db-1.8.7, db-1.9.3, db-2.0.0 という、リファレンスを格納するデータベースディレクトリが作成されます。

2. bitclust のセットアップ

https://github.com/rurema/bitclust を clone します。

$ git clone git@github.com:rurema/bitclust.git

bitclust というディレクトリができるので cd し、以下のコマンドを実行します。

$ bundle install

その後、以下のコマンドを実行し、データベースディレクトリへのシンボリックリンクを作成します。

ln -s /tmp/db-1.8.7
ln -s /tmp/db-1.9.3
ln -s /tmp/db-2.0.0

3. リファレンスの記述

リファレンスの元になるデータは、doctree/の中に入っているテキストファイルです。ディレクトリ構成は以下のようになっています。

• doctree/
  • refm/
    • api/
      • src/
        • ここに標準添付ライブラリのリファレンスが含まれます。
        • _builtin/
          • 組み込みライブラリのリファレンスが含まれます。
    • capi/
      • Rubyの拡張ライブラリ用のC APIのリファレンスが含まれます。
    • doc/
      • トップページや「Ruby言語仕様」など、その他のリファレンスが含まれます。優先順位は低めです。
    • old/
      • 旧リファレンスマニュアルの雑多なコンテンツのコピーです。Webからは見られません。
  • faq/
    • 旧リファレンスマニュアルの、Ruby FAQのデータのコピーです。いまのところ、Webからは見られません。

リファレンスはRDに似た書式で書かれています。テキストファイルなので、中身を見れば、なんとなく書き方が分かると思います。正確な書式についてはReferenceManualFormatDigestを参照してください。

さて、では実際にリファレンスを編集してみましょう。

TODO

4. プレビュー

bitclust ディレクトリに cd して以下のコマンドを実行します。

$ bundle exec rackup config.ru

ブラウザで http://localhost:9292/ を開くと習性済みのリファレンスマニュアルを閲覧できるので、修正箇所の内容を確認します。記述が間違っていないか、リンクが間違っていないかなどに注意してください。

5. パッチを送る (Pull Request)

確認が終わったら、 doctree ディレクトリに cd して修正内容をコミットし、リモートリポジトリに push します。

$ git add .
$ git commit
$ git push

push できたら GitHub の自分の fork のページから Pull Request を行います。