起動引数・環境変数の詳細な仕様についてdocs/にドキュメントを作りたい

[aoirint]

内容

#711 (comment) で挙がった内容をふまえて、Issue化します。

起動引数や環境変数の説明は、ArgumentParser.add_argumentのhelp引数で設定しています。
この内容はpython run.py --helpに出力され、出力内容をREADMEに記載しています。

現在のhelpの内容は、起動引数と環境変数の優先順やデフォルト値などの詳細な仕様を知るには十分でなく、コードを読む必要があります。

しかし詳細な挙動をhelpに記述すると、python run.py --helpの出力が長くなり、ターミナルやREADMEの限られた紙面では読みにくくなります。

docs/以下に仕様を説明するMarkdownドキュメントを追加して、起動引数・環境変数を変更する場合に合わせて更新するようにしたいです。

Markdownドキュメントを手で書く以外でも、プログラム中に記述する方法や自動生成する方法などがあれば検討したいです。
他のプロジェクトのドキュメントの例があれば参考にしたいです。

たたき台: https://gist.github.com/aoirint/1c17899193b9509c9768acfe6379d670

いまのところ、上のたたき台の感じのドキュメントを考えています。

Pros 良くなる点

• エンジンを直接使うユーザが仕様を理解しやすくなる
• 開発者によって起動引数と環境変数の優先順やデフォルト値の挙動が変わりにくくなる

Cons 悪くなる点

• 引数・環境変数を変更するプルリクエストの負担が増える

実現方法

• ドキュメントに書く内容を決める
  • 起動引数・環境変数によって設定される内容
  • 起動引数の名前
  • 環境変数の名前
  • 設定値が空文字列の場合の取り扱い
  • デフォルト値
  • 例となる設定値
  • フローチャート
• コア側、依存ライブラリ側で読み取る環境変数があれば、書くかどうか決める
• ドキュメントをどのようなフォーマットで書くか決める
  • おおまかなテンプレート
  • ファイルの配置・分割単位
• ドキュメントを追加する場所を決める
  • リポジトリのdocs/以下
• ドキュメントを追加する単位を決める
  • 少しずつ追加する
  • 一気に追加する
• ドキュメントを作って追加する
• 優先順や空文字列の取り扱いなどの仕様が統一されていない箇所があるか調べる
• 仕様の統一（破壊的変更）を入れるか決める

VOICEVOXのバージョン

0.15 開発版

その他

[Hiroshiba]

方針良さそうに感じました！！　叩き台もパッと見ですがいい感じな気がします

他のプロジェクトのドキュメントの例があれば参考にしたいです。

僕たちも依存してるuvicornとか参考になりそうかも。https://www.uvicorn.org/settings/
たぶん全引数に対して環境変数があるっぽみでした。こうすればドキュメントも簡単でなるほどでした。
clickが使われているっぽみです。

---

ドキュメントはわりとユーザビリティとメンテナンス性のトレードオフになると思うので、どれぐらい需要あるかを考慮して力入れ具合を定めたいですね！
ドキュメントが必要になるほど詳細に知りたい人はエンジンのユーザーではなくエンジンを使った開発者なので、まあだいぶ少ないだろうなとは思います。
それを前提にリストアップしてくださったのをコメントするとこんな感じでしょうか。

• コア側、依存ライブラリ側で読み取る環境変数があれば、書くかどうか決める
  • 需要ありそうなのは書いてもいい気がします！
• ドキュメントを追加する単位を決める
  • やりやすい形でOKです！
  • 先にがっつり仕様の方を変えちゃってからドキュメント作る方針だと手間が減らせるかも、ぐらい
• 仕様の統一（破壊的変更）を入れるか決める
  • 重要なの（エディターの0.14.8から依存されているもの、サードパーティがよく使いそうなもの）以外はOKだと思います
  • 以前のパラメーターをdeprecatedとしてしばらくサポートできるとかっこいいかも。できたらいいな～ぐらいの気持ちです
• 設定値が空文字列の場合の取り扱い
  • これ僕たち側は把握しないといけないことだけど、ユーザー側はそもそも空文字を指定したいことがないので省けるかもです
• フローチャート
  • これは結構メンテナンスが大変なので省きたいかもです（あと意外とテキストの方が分かりやすそう）
  • あと表もちょっと作るの大変なので省けるかも

ドキュメントは利用者のためにあることを念頭に置けば取捨選択できるかなと！
（一つ一つこちら側で判断必要であれば申し付けください 🙏）

[github-actions]

本 Issue は直近 180 日間で活動がありません。今後の方針について VOICEVOX チームによる再検討がおこなわれる予定です。