この記事は2020年ふりかえりアドベントカレンダー 2日目です。昨日の記事は 2020年の終わりと2021年に向けての準備をするぞという気持ち - いまブログ です。
Ruby リファレンスマニュアルとは
Ruby の日本語版の公式ドキュメントです。略して「るりま」と呼びます。Ruby を書いたことがある方なら一度は読んだことがあるのではないでしょうか。
オブジェクト指向スクリプト言語 Ruby リファレンスマニュアル (Ruby 2.7.0 リファレンスマニュアル)
るりまは GitHub 上で管理されていて、誰でも修正したり、議論することができます。今回は、るりまを修正したい、気になる点を挙げたい、と思ったときにどうやったらいいのかということを書きます。
るりまのリポジトリ：rurema/doctree: Repository of Japanese Ruby reference manual
ちなみに「るびま」は Rubyist Magazine の略で使われることが多いです。面白く勉強になる記事がたくさんあるのでおすすめです。
るりまを修正する方法
GitHub に issue を立てたり、PR を送ることで修正できます。
issue を立てる方法
誰でも GitHub 上で issue を作成できます。
issue の内容は、
- ドキュメントの単純な誤り指摘（バージョン間違いなど）
- ドキュメントをより良くするための提案（説明文追加など）
- サンプルコード提供
- 既に上がっている issue に対するコメント
など、なんでもOKです。
PR を送る
具体的に修正したい箇所が決まっている場合は、PR を送ると反映されやすいです。
このとき、リファレンスマニュアル用の記法を使わない場合（誤字修正、サンプルコード追加など）は GitHub 上で直接修正すると楽です。
リファレンスマニュアル用の記法を使う場合（バージョンによって違う書き方をしたい場合など）は fork して修正して HTML を確認して push するとよいです。
GitHub 上で直接修正する方法
fork していない場合は先に GitHub で rurema/doctree を fork しておきます。
るりまで編集したいページの右上の方にある [edit] リンクを押します。
GitHub 上で修正します。
差分を確認します。
commit メッセージを書きます。
あとは Propose changes を押せば PR を送れます。簡単ですね！
fork してローカルで修正して PR を送る方法
Tutorial · rurema/doctree Wiki にとても詳しく書いてあります。抜粋してここでも書きます。
fork します。
ローカルに clone します。
$ git clone https://github.com/自分のアカウント名/doctree.git rubydoc $ cd ./rubydoc
ブランチを切ります。
$ git checkout -b ブランチ名 Switched to a new branch 'ブランチ名'
好きなエディタでドキュメントを修正します。
リファレンスマニュアルの書式のまとめは ReferenceManualFormatDigest · rurema/doctree Wiki にあります。
bitclust をインストール、セットアップします。これでるりまのファイルから HTML ファイルを生成できるようになります。
$ gem install bitclust-core bitclust-dev refe2 $ bitclust setup
HTML ファイルを生成します。
bitclust htmlfile コマンドで生成できます。たとえば、
$ bitclust htmlfile ./refm/api/src/_builtin/Array --target=Array#pop --ruby=2.5.0 > /tmp/Array_pop.html
とすると、 Array#pop の Ruby 2.5.0 版の html が /tmp/Array_pop.html に作成されます。このファイルをブラウザで開くことで、生成されるHTMLを確認できます。
bitclust htmlfile の詳細についてはこちらにまとまっています。BitClust · rurema/doctree Wiki
html が問題なく生成できることを確認します。
commit します。commit メッセージは日本語でも英語でもかまいません。
$ git add . $ git commit
remote に push します。
$ git push origin <ブランチ名>
PR を作成します。
push すると rurema/doctree から Compare & pull request できるようになっています。
そこから PR を作成します。
PR は日本語でOKです。
できました。
困ったことがあれば
Slack の ruby-jp に #rurema チャンネルがあり、質問することができます。
まとめ
るりまを読んでいて、この説明よくわからないな〜とか、もっとサンプルコードがほしいな〜とか、誤字かも？と思ったそのときがコントリビュートチャンスです！
るりまは OSS ですが日本語で issue や PR をつくっていいので、気軽にコミュニケーションができます。また、OSS に PR を送る一連の流れの練習にもなります。
どんどんるりまをよりよくしていきましょう！
