Redmine本体のリファレンスをバージョン情報付きで生成する
この記事は Redmine Advent Calendar 2018の12/15分です。今日はRedmineのプラグイン開発用にRedmineのドキュメントにバージョン情報(いつから使えるか)を含めるというお話しです。以下の画像右側のような感じです。yardにuntilタグがないので、ちょっと見た目が悪いですね...
これはRedmine本体のIssue#each_notificationが2.4.0から4.0.0の間で使える事を示しています。
それらを機械的にRedmineのバージョンごとに見れるようにしたものが以下です。
- http://sho-h.github.io/redmine/3.3/index.html
- http://sho-h.github.io/redmine/3.4/index.html
- http://sho-h.github.io/redmine/4.0/index.html
とりあえずまとめ
リンク先もしくは画像にあるようにSince
明日は @onozaty さんの予定です。お楽しみにー。
蛇足(やりかた)
以降はどうやって生成したかです。気になる人向け。
- Redmine本体のリファレンスの生成
- バージョン情報がないのでねじ込む
1. Redmine本体のリファレンスの生成
Redmineのリファレンスはyardで記述されています(正確にはrdocとyardのドキュメントが混在しているのですが...)。production環境以外ならbundle install後すぐに以下のコマンドでdoc/app以下にリファレンスを生成できます。
$ bundle exec rake yard
この後でdoc/app/index.htmlを開くとリファレンスが参照できます。なお、ありがたい事にここまでの情報は以下で公開されています。
ただし、このままだと現状のメソッドに関する記述はわかりますが、それぞれのメソッドがいつから使えるかわかりません*2。僕自身もredmine_auditという運用中のRedmineで更新が必要な脆弱性の対応がリリースされたら通知してくれるプラグインを作っているのですが、そこではRuby x Redmineの組み合わせで単体テストを実行しています。ですが、そもそもRedmine本体のメソッドを使う前にもう少し情報が欲しい感じです。
2. バージョン情報がないのでねじ込む
という事で生成時に機械的にねじ込みます。大まかには以下のようにするだけです。
- yardで各バージョンの.yardocを生成
- yard diffで各バージョンの.yardocを比較してバージョン情報の一覧を生成
- yardocのテンプレートを修正してリファレンス生成時にバージョン情報をねじ込み
バージョン情報の一覧はここに置きました。この辺は細かい話しは別記事を参照してください。最後にどうバージョン情報をねじ込むかですが、yardocは自分で作ったテンプレートが指定できます。それとバージョン情報の一覧を混ぜてやれば完成です。今回はテンプレート内でYARDの各種オブジェクト(MethodObjectなど)にadd_tagしているだけです。強引すぎる。
具体的には以下でやっています。この修正自体はRedmine本体をforkして入れてますけど、プラグインにしてタスクだけ生やしてしまうのがいいかもしれませんね。
ところで yard diff と @sinceタグ を組み合わせるこの手順はRedmineに限らず使えるので便利ですね。(本当におしまい)
2018/12/16: 画像や文言等を少し修正。
