tl;dr;
ファイルに @title を埋め込むかyard用の中間ファイルを作る
コンテキスト
例えば下記のようなファイル構成があったとします
- README.md
- sub-dir/README.md
https://github.com/lsegal/yard でドキュメントを作るとファイル一覧で同じものが並ぶのでなんとかしたかったというのが発端
方法1: ファイルに @title を埋め込む
https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#adding-meta-data-to-extra-files を参照。
これでもいいんだけどGitHubとかで見た時にyardのタグが見えるので見栄えが悪いのがちょっと難点。
方法2: yard用の中間ファイルを作る
.yard/sub-dir-README.md のような名前で sub-dir/README.md をincludeするような中間ファイルを作成。
{include:file:sub-dir/README.md}
.yardoptsなどで下記のように中間ファイルのパスを渡す。
.yard/sub-dir-README.md
こうすることで sub-dir/README.md にyardのタグを書かずにファイル一覧をいい感じにできます。
go-gem-wrapperでこの問題に困ってこっちの方法を採用しました。
マージした後で気付いたけど .yard/go_gem_README.md に @title 書いてもよかったかも。
中間ファイルが増えるのもちょっと微妙だけど自分はこっちの方がまだマシかなという判断。異論は認める
