私もリファレンスを書いてみたいわ!という方のためのチュートリアルです。このエントリは定期的に見直されるべきです。
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 という、リファレンスを格納するデータベースディレクトリが作成されます。
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
リファレンスの元になるデータは、doctree/の中に入っているテキストファイルです。ディレクトリ構成は以下のようになっています。
- doctree/
- refm/
- api/
- src/
- ここに標準添付ライブラリのリファレンスが含まれます。
- _builtin/
- 組み込みライブラリのリファレンスが含まれます。
- src/
- capi/
- Rubyの拡張ライブラリ用のC APIのリファレンスが含まれます。
- doc/
- トップページや「Ruby言語仕様」など、その他のリファレンスが含まれます。優先順位は低めです。
- old/
- 旧リファレンスマニュアルの雑多なコンテンツのコピーです。Webからは見られません。
- api/
- faq/
- 旧リファレンスマニュアルの、Ruby FAQのデータのコピーです。いまのところ、Webからは見られません。
- refm/
リファレンスはRDに似た書式で書かれています。テキストファイルなので、中身を見れば、なんとなく書き方が分かると思います。正確な書式についてはReferenceManualFormatDigestを参照してください。
さて、では実際にリファレンスを編集してみましょう。
TODO
bitclust ディレクトリに cd して以下のコマンドを実行します。
$ bundle exec rackup config.ru
ブラウザで http://localhost:9292/ を開くと習性済みのリファレンスマニュアルを閲覧できるので、修正箇所の内容を確認します。記述が間違っていないか、リンクが間違っていないかなどに注意してください。
確認が終わったら、 doctree ディレクトリに cd して修正内容をコミットし、リモートリポジトリに push します。
$ git add . $ git commit $ git push
push できたら GitHub の自分の fork のページから Pull Request を行います。