naniwa.rb #9 PicoRuby

以下は ruby-jp.slack.com の #PicoRuby チャンネルの https://ruby-jp.slack.com/archives/C02041FHVBN/p1686114098708229 を転載しています。

やりたいこと

• mruby、mruby/c（PicoRuby）のペリフェラル API 共通規格のドキュメントを整備したい

ペリフェラルとは

• マイコンの入出力に関する各種の規格
• 今回の対象になりそうなのは、GPIO, ADC, I2C, API, UART, PWM

mruby、mruby/c の「共通規格」とは

• 軽量 Ruby フォーラム（mruby のメンテ主体）、九州工業大および ITOC（mruby/c のメンテ主体）の共同の取り組み
• マイコンでの Ruby 利用を促進するため、標準的な API 規格を策定する（している）。そして公開したい（← これが重要）
• わたくしハスミは、mruby/c のメンテナのひとりとして関与している
• まつもとさんはあんまりマイコンに詳しくないので、基本的にはこちらに任せてくれている

現状どうなっているか

• 大まかな規格案はすでにある： https://github.com/hirohitoHigashi/mruby_io_class_study/
• それを PicoRuby の（RP2040 用）ライブラリとして実装しつつある： https://github.com/picoruby/picoruby/tree/master/mrbgems （この中の/picoruby-(gpio|adc|i2c|spi|uart)/）

↑ ここまでは関係者の共通認識です。

↓ ここから下はわたくしの個人的な考えですが、このドキュメント計画をほかに強く駆動する人はいないし、前向きな提案はだいたい受け入れられるので、うまいことやっていきたいと思っています

成果物はどんなものか

• マイクロパイソン先輩みたいなウェッブページ （GPIO の例）https://docs.micropython.org/en/latest/library/machine.Pin.html
• このような HTML を簡単にメンテナンスできる仕組みをつくりたい
• デプロイ先は mruby または mruby/c の GitHub Pages あたりか？
• 英語だけでいいと思う

スケジュール

• ことしの 8 月くらいに世に出したい

どんな仕組みだとよいか。ここからは妄想

• RBS から自動生成する仕組みがほしい（そういえば大倉さんがどこかでそんな話をしていたような...？）
• RBS はこういう風に書いてます：https://github.com/picoruby/picoruby/blob/master/mrbgems/picoruby-gpio/sig/gpio.rbs
• もちろんこれだけだとドキュメント情報として足らないので、説明文をコメントに書いたりするのはやぶさかじゃない
• RBS に書いてある情報は、RBS だけで完結したい（コメント側に重複する情報を書きたくない）
• 「RBS + コメント情報」を YARD（以下、YARD を RDoc に読み替えてもよいです）に変換するとか？（この辺テキトウに言ってます）
• そういう生成が難しければ、最初から YARD でもいい
• GitHub Actions などにより自動でデプロイされるとうれしい。それはそう
• 「何をもとに生成するか」という問題はある。いつまでも picoruby-(gpio|adc|etc.)がリファレンス実装でありつづけるとは限らない。ただ、とりあえずは既存の picoruby-gpio が元データでよいと思う

要するにこういう話かな？

• なるべくメンテナンスが楽な方法で、
• HTML をどう生成するか、
• その実装をだれがやるのか

将来的な展開

• ここでは「マイコンペリフェラルの API」の話をしているが、もっと広げられる可能性がある
• mruby と mruby/c とでは組み込みライブラリの仕様に大きな違いがあるので、それらのドキュメントもほしい（これ実は結構めんどうかもしれなくて、Matz 謹製 mruby と言えども CRuby の仕様との相違がわりとあり、正確にドキュメント化するのは工数がかかりそう。なのでこれはいまのとこスコープ外）

当面の進め方（案）

• 参加者をここで募る
• 基本的なアイデア出しもここ（または mruby/c の Slack）でやる
• 早々に行き詰まると思う（確信）ので、
• オンラインで話す。そしてまた進め方を考える