るりま大刷新計画2022最終報告
- 応募者名: 株式会社 Ruby 開発
- 担当: 西山和広、尾田博仁
プロジェクト概要
Ruby リファレンスマニュアルを生成するために現在はbitclustを利用している。bitclust は RD に独自のプリプロセッサなどの機能を足し、インライン記法などを変更した RD ベースの記法を使っている。 現在 RD ベースの記法はポピュラーではなく、Ruby リファレンスマニュアルのコントリビュートをしようとしても、RD ベースの記法を習得することが困難な状況にある。 そこで、本プロジェクトではドキュメントのソースを RD ベースの記法から、現在プログラマーの間で最もポピュラーだと思われる Markdown ベースの記法への移行を目指す。
成果
- Markdown 処理系などの調査、るりま関連プロジェクトへの影響調査、ドキュメントシステム bitclust での入力の最低限の Markdown 対応、最低限の HTML への出力の対応まで実施して、実現可能性であると確認した。
- 入力に関して、ライブラリ単位(doctreeのrefm/api/src/LIBRARIESの行ごと)での対応は、既存の部分はほぼそのままで、追加機能として Makrdown 対応可能だとわかった。しかし、コードブロックの中のコメントなどで見出しと誤解する記述が書かれやすいため、簡易実装ではなく、Markdown パーサーの結果をきちんと利用することが必要だと判明した。
- 出力に関して、HTML 出力は基本的な部分は、大きな機能追加せずに既存の出力と同じようにできるとわかった。リンクの独自記法などで追加機能が必要となったので、出力の調整のため、こちらも Markdown から HTML の変換をそのまま利用するのではなく、追加実装が必要だと判明した。
調査したもの
- https://spec.commonmark.org/0.30/: markdown にない機能はどうすればいいのか参考にするため、仕様を参照した。processing instruction の利用を考えたが、最終的に jekyll に合わせて liquid を使うことにした。
- https://github.com/cpprefjp/site などの他の Markdown ベースのリファレンスサイトでメタ情報の記述方法などを参考にした。
- jekyll: markdown から HTML への変換をする処理系として参考にした。www.ruby-lang.org で使われているため、同じ仕組みを使うとリリースノートなどの markdown を相互利用しやすくなるという利点がある。
- liquid: jekyll で使われているプリプロセッサで、タグやフィルターなどで拡張可能。参考: https://jekyllrb.com/docs/liquid/
- kramdown: jekyll でも使われている markdown 処理系で GitHub Flavored Markdown (GFM) にも対応している。
- るりまサーチ: bin/bitclust-indexerでbitclustのデータベースを直接みていることを確認して、データベースを変更すると影響があるとわかった。
- bitclust: 変更対象のドキュメントシステム。
- doctree: 変更対象の日本語リファレンスマニュアル。
ドキュメント記述者向けの情報
bitclust markdown 記法として現状の記法の説明を作成した。
内部 db の変更点
source_locationと同様にsource_formatを bitclust の db のメタデータに保存するようにして、dbを利用するアプリケーションが区別できるようにした。
Known Issues
#@includeが RD と MD の混在に未対応 (bitclust のプリプロセッサでの処理のため、_builtinの一部だけ MD にするのが難しい)- 見出しによる分割を kramdown を使わずに独自でやっていると code blocks の中に
# commentがあるとエラーになるので、kramdownの解析結果のオブジェクトツリーをきちんと使うようにする必要がある - kramdown での変換は最低限の動作確認で試した記法以外は未調整
- liquidでのプリプロセスも変数やフィルターはバージョン分岐の動作確認のみで未調整
今後の予定
- 見出しによる分割にも kramdown パーサーの結果を利用するようにして、RD記法のパーサーを元にした独自のパーサーを止める
- liquidによるプリプロセスの調整
bitclustへの markdown 対応のマージ- ドキュメント記述者向けのドキュメントを充実させる
doctreeのrefm/api/src/LIBRARIESでわかれているライブラリから markdown 対応していく_builtinは最後にまとめて変換で対応するか、@includeでの混在が実装できれば個別に対応していくrbsなどとの連携を進めていく