追加: VVM ファイル詳細 docs

[tarepan]

内容

概要: VVM ファイル docs にファイル詳細（定義・内部構造・例）を追加した

VVM の詳細を記述する docs が存在しないため、既存 docs への加筆により情報を補足した。
これにより、v0.16 リリース issue (#545) の「[ ] VVMのマニフェストのデータ構造に関してメモをどこかに書く」が解決される。

関連 Issue

ref #545

[qryxip]

個人的な意見ですが、リポジトリ内のドキュメントを利用者向けと貢献者向けに分類するとき、VVMの内部構造については後者に分類されると思っています。

というのも利用者向けとしては我々的に保証はしたくない部分が結構あると思っていて、例えばZIPファイルとしてのファイル構造は、今後ソング用VVMが入ってくるとonnxファイルのセットが異なってきます (#761 で考えているように、{talk, singing_teacher, frame_decode}²で2³通りの構造を考えることになるかなと思っています)。またmanifest.jsonの形式も変える予定です。

(edit) (現時点ではまだ無い)vvm_format_versionの存在ならユーザーに教えてもいいかもしれません (unzip -pとjqを使って読むコマンド付きで)。

なのでdocs/vvm.mdにドキュメントを書いてREADMEからリンクする、というのが良いのかどうかがわからないです。

@Hiroshiba 「VVMのマニフェストのデータ構造に関してメモをどこかに書く」というの、私はあまりよく覚えていないのですがどんな動機でしたっけ?

[Hiroshiba]

@qryxip 貢献者向けですね！

このコメントを見るに

開発者向けに、VVMのマニフェストの構造に関してのメモがどこかにあると良いなと感じました。

とのことでした。

だから利用者向けのとこからはリンクを張らず、貢献者向けのとこからリンクをはるのに賛成です！

[tarepan]

リポジトリ内のドキュメントを利用者向けと貢献者向けに分類

この2分類の場合、@qryxip さんと @Hiroshiba さんに同意です。

ただ、（ENGINE でも似た議論があったのですが、）実際のリポジトリ利用者は 3 種類います。

• 利用者
• 開発者（clone / OSS forkする人）
• 貢献者

です。

CORE の README.md はユーザーガイド節で別ページリンクを貼っています。
なのでそれ以降の記述は「開発者」「貢献者」向けとなるはずです。
この2者向けであれば、むしろ DX 向上のために VVM 詳細をリンクする方が好ましいと考えます。（CORE fork で VVM の理解に苦労したためこの PR を建てました。）
今回リンクを追加した 環境構築 節は ユーザーガイド 節以後に配置されているので、上記の条件に当てはまると考えます。

よって本 PR の箇所にリンクを張る方向性を支持します。
お二人のご意見を伺えれば幸いです。

[Hiroshiba]

たしかにです！

となるとREADMEのだいぶ下の方で「VVMの内部構造」みたいなサブタイトルを付けつつ案内して、これはユーザー向けに保証してるものではないと案内するとかでしょうか。
あるいは、vvmを読み込む部分のコードにドキュメントのパスを書くのが良い気がしました！（こっちのが合ってそう）

一旦READMEなどからはリンクを張らず、あとでしかるべきところを探して足すとかもありだと思います。

[tarepan]

vvmを読み込む部分のコードにドキュメントのパスを書く

👍
良いアイデアに感じました。
README.md を読む時点では VVM のこと知らない開発者/貢献者が大多数なので、それを知る段階の1つであるコードにコメントとしてドキュメントリンクを書き記すのは有用そうです。

@qryxip さんの意見を伺ったうえで判断したいと思います。

[qryxip]

少なくとも現状からの一歩としては最善だと思いました。それでいきましょう。

(そろそろドキュメントをガンガン改善していきたいですね)

[tarepan]

@qryxip @Hiroshiba
全指摘箇所の反映・テストパスを確認しました。Re-review よろしくお願いします。

[qryxip]

LGTM!

[Hiroshiba]

LGTM！！