利用者向けのしっかりしたドキュメントやポータルを作る？

[sevenc-nanashi]

内容

コアを利用する開発者のための開発者向けドキュメントみたいなのがあると便利そうです。

Pros 良くなる点

• 利用者に優しい

Cons 悪くなる点

• メンテコストが増える

実現方法

ここら辺が候補になりそうかなと：

• Vitepress：主にJS界隈で使われている印象。Vite、Shikiなど。
• mdBook：主にRust界隈で使われてる印象。wasm-bindgenなど。

VOICEVOXのバージョン

0.17.0

OSの種類/ディストリ/バージョン

• Windows
• macOS
• Linux

その他

関連しそう：

• ドキュメントを整理・改善したい #496

[sevenc-nanashi]

具体的にはこんな内容があると優しいと思います：

• 各API（C、Py、Java）へのドキュメントのリンク。
• 各言語でのGetting Started（例えばインストール方法）
• Voicevox OnnxruntimeとOnnxruntimeの違い：VOICEVOX onnxruntimeとはなにか、onnxruntimeとの違いが利用者にとってわかるようにしたい onnxruntime-builder#79
• ダウンローダーの詳細な使い方（例えばGitHub Actions用のレシピとか？）

デプロイ場所はvoicevox_coreのGitHub Pagesあたりだと思います。
（エンジンのドキュメントも足すのもアリ？それならvoicevox/dev_portalみたいな感じのリポを作ってそこでやったほうがURLの見栄え的にも良ささう）

[sevenc-nanashi]

これは完全に妄想も含まれますが：
ドキュメントサイト自体がレジストリになっていると楽しそうです。
具体的にはこう言うことをすると思います： https://github.com/sevenc-nanashi/vv_core_registry/blob/main/inject.ts

[Hiroshiba]

issue作成ありがとうございます！
見やすいサイトは個人的に結構大事だと思っているので、何かしらの形でいつか作りたい気持ちはあります！

最初はミニマムスタートの方がいいと思うので、一番需要が高そうなコアから始めるのが良さそうに感じるのですが、あとあとVOICEVOX全体にスケールしていきたい気持ちも少しあります。
途中で URL は変わりうるとして、徐々にスケールアップしていくにはどうすれば良いでしょうか？
最初はCORE専用でページを作っていき、あとあとENGINE用とかも足していきたいけど、ENGINE用とかを足すときにアーキテクチャをごそっと変えなくてもいいようにスケールアップしたい感じです（説明が難しい。。）

[sevenc-nanashi]

とは言ってもエンジンのサポートを足すのは多分ページを増やすだけなのでそれほどアーキテクチャは変わらないような気がします。

あとURLは可能な限り変えない方が良さそう、リダイレクトが面倒なので...

[Hiroshiba]

コアだけならページ数そこまで量無いと思うので、エンジン足してもあまり変わらなそうに感じます。
まあ逆に言うとコアだけのときに凝ったことはやらない、という感じかな。

URLをどうするかはまあリリースするときまでに決めると良さそうです。
最悪「こちらに移動しました」というページだけを表示するとかでもまあ。

[sevenc-nanashi]

vitepress、なんかこう、仰々しいというか...って感じでした。

スクショ

[sevenc-nanashi]

mdbookはこう、身の丈に合ってるというかなんというか...って感じだったのでこっちを推したいです。

Details

[Hiroshiba]

ほんとだ、なんかちょっと大層な感じ出ちゃいますねｗ

mdBook側、ヘッダーがなさそう？
仮にエンジン・コア・エディタと並ぶとき、概念が多層化していてこのヘッダー部分無いと移動が大変そうだな〜という直感があり、ヘッダーはほしいかもなぁと少し感じました！

そのウェルカムページだけ表示させない方法とかはなさそうでしょうか。
その「３つの特徴」みたいな欄がなければ意外とありかも。
まあでもここに「エンジン」「コア」「エディタ」並べれば良い気がするので、Vitepressでも良いのかも･････？

[sevenc-nanashi]

そのウェルカムページだけ表示させない方法とかはなさそうでしょうか。

調べてる限りだとないんですよね。

もういっそmarkdownItとかで作った方が手っ取り早いかも？（docs/下をglobしてルートを生成みたいな感じの）

[Hiroshiba]

まあカッコよくするのは後でもできるので、まずは既存フレームワークに乗っかって爆速でそれっぽいの作るのが良さそうな気がします！！

[sevenc-nanashi]

そういえば：
docusaurusを試しました。

Details

やっぱりみんな三つの特徴を入れたがる...

[sevenc-nanashi]

あ、エディタのドキュメントは入れない想定でした（エディタ内のQ&Aで済ませる）

別の話：Vitepressのトップページにリダイレクト仕込んでトップページ自体を消し去るのはアリかも...？

[qryxip]

個人的にはCOREでは、Polarsのユーザーガイドみたいに言語タブ的なものがあると嬉しいです。

Polarsで使われているのはMaterial for MkDocsのタブ機能。Docusaurusにも同様のものはあるっぽい。mdBookには…一応mdbook-tabsというのはあるけど…

[Hiroshiba]

そのタブ機能はVitepressにCode Groupsとして公式実装されてそう？
https://vitepress.dev/guide/markdown#code-groups

[sevenc-nanashi]

vitepress、そもそもイケたトップページを作らないことも正当な方法で可能なのでVitepressでよさそう？

[Hiroshiba]

今の迷いポイントメモ：

• バージョン違いどうするか
• リポジトリ分けるかどうか

バージョン違いは破壊的変更少ないだろうとみなして、考えなくても良いかも。
新機能にはバージョンバッチつければ。

リポジトリ分けるかどう決めればいいかわからないなぁ。
リポジトリ同じだとドキュメント変更とかテストがやりやすそう。ただドキュメントのデプロイやdev起動は複雑になる。
まあ別PR出せばいいだけだし、分ける･･･････？

discordのこの辺りのコメントから抜粋

名無し｡ — 今日 14:27
vitepress、イケたトップページを正当に破壊できたのでこれでよさそう
画像
名無し｡ — 今日 14:35
https://vitepress.dev/reference/default-theme-team-page
VitePress
VitePress | Vite & Vue Powered Static Site Generator
画像
なんかよく見る開発者チーム表示もできるっぽい
ヒホ — 今日 14:43
VitePress良さそうな雰囲気！！　あと気になるのは･･･もう無い気がする
i18nとか･･･？いやまああるだろうし･･･
名無し｡ — 今日 14:43
リポジトリ運用？ > 気になるところ
https://vitepress.dev/guide/i18n i18n
VitePress
VitePress | Vite & Vue Powered Static Site Generator
画像
ヒホ — 今日 14:45
i18nはたぶんcrawdinと連結できそうな雰囲気を感じる
リポジトリ運用、コアのリポジトリで作れるのが一番良いけど、流石に別リポジトリのが良いんだろうか
名無し｡ — 今日 14:46
エンジンにスケールするみたいな話も出てた記憶
ヒホ — 今日 14:46
まあそれは後での話かな
名無し｡ — 今日 14:48
コアリポジトリでも作れると思います、でもCrowdin突っ込む（=New crowdin updatesのPRがたくさんできる）となると別リポのほうがよさそう
でもコアのリポでやるとタグとかが一緒にできて便利というのも判る
ヒホ — 今日 14:48
リポジトリ別だとバージョンが統一できないのが厄介なんですよねぇ
あ　ちょっと話変わるけど、バージョンを別にしたりはできるんだろうか。pythonの上にあるバージョンセレクタみたいな
例 https://docs.python.org/ja/3.13/library/enum.html
名無し｡ — 今日 14:50
https://vitepress.dev/reference/default-theme-nav#navigation-links
VitePress
VitePress | Vite & Vue Powered Static Site Generator
画像
Vitepressの既存サイトはここら辺で実装されてそうな予感
ヒホ — 今日 14:51
無理なら、バージョンいくつからの新機能だということがわかるような表記ができると嬉しそう
こういう感じ https://ja.vuejs.org/guide/built-ins/teleport.html#deferred-teleport
名無し｡ — 今日 14:52
https://vitepress.dev/reference/default-theme-badge
VitePress
VitePress | Vite & Vue Powered Static Site Generator
画像
これかな
サイト毎分けてるのがそこそこある印象
Vite、vue-i18n、Vueはそう
ヒホ — 今日 14:54
エンジンやコアを一緒のサイトでまとめる場合、分けづらいんですよねぇ
名無し｡ — 今日 14:55
実際そう
コアとエンジンでそれぞれにvitpressを設置した方がきれいにまとまりそう
遊んでる
画像
ヒホ — 今日 15:01
過去バージョンをなんかいい感じに解決できる方法があればコアもエンジンもあわよくばエディタもまとめちゃいたいんだけどなーーー
エディタはコントリビューションガイドラインとか、あとはエンジン起動情報のドキュメントとかがある
名無し｡ — 今日 15:02
メジャーバージョンの変化時にドメインごとわけて、それ未満は3.3.4をつけるみたいなのが多いかな
ヒホ — 今日 15:05
過去の互換性を超破壊するタイミングはまだ先だろうし、そういう意味ではコアもエンジンもエディタもドメイン変えるようなアップデートは無い･･････････かも･･････？
名無し｡ — 今日 15:05
とりあえずドメイン破壊はしばらくはなさそうでいいかな
ヒホ — 今日 15:06
リポジトリが別なことにより問題が生じないかはちょっと考えたいかも
名無し｡ — 今日 15:06
色々遊んでるけど、どうやらニコニコのアイコンも入っているらしく、すごい
画像
名無し｡ — 今日 15:06
コアのPRで一緒にドキュメントを更新できないのは少し面倒かも
まぁGitHubのcronとかでpullしてデプロイ、を別リポジトリでやればよさそうだけど
ヒホ — 今日 15:08
Vueとかミスキーとかの運用どうなってるのか参考に調べといたほうが良さそう感
名無し｡ — 今日 15:10
ここっぽい：https://icon-sets.iconify.design/simple-icons/page-2.html?keyword=simple
Iconify - home of open source icons
Open source vector icons from all popular icon sets
Iconify - home of open source icons
名無し｡ — 今日 15:17
Vue：別リポジトリ、https://github.com/vuejs/docs
Misskey Hub：別リポ、https://github.com/misskey-dev/misskey-hub-next
Vite：同リポ、https://github.com/vitejs/vite/tree/main/docs
ヒホ — 今日 15:19
結構リポジトリ分かれてるのもあるんですねーーー
ドキュメントの更新はどうやってるんだろ
「別PR送ってください」？「ドキュメントは別チームが作ります」？あるいはcronが動いてる…？
名無し｡ — 今日 15:25
辿ろうとしたらブランチ消えてて草
別PR送ってそう
ヒホ — 今日 15:41
viteは言語ごとにリポジトリ別れてて、本家で変わったらissueが自動で富んでくる形になってるっぽい
https://github.com/vitejs/docs-ja/blob/main/CONTRIBUTING.md
ヒホ — 今日 15:48
うーーーーーーーーーん
バージョン違いどうするかと、リポジトリ分けるかどうかかなり迷いますね。。。

今のとこの結論として、バージョン違いは破壊的変更少ないだろうとみなして、考えなくても良いかも。
新機能にはバージョンバッチつければ。

リポジトリ分けるかどう決めればいいかわからないなぁ。
リポジトリ同じだとドキュメント変更とかテストがやりやすそう。ただドキュメントのデプロイやdev起動は複雑になる。
うーーーーん　まあ、別PR出せばいいだけだし、分ける･･･････？

[sevenc-nanashi]

とりあえず分けてリポジトリを作ってみようと思います。
名前は...シンプルにvoicevox/docsとか...？

[Hiroshiba]

完成するまではダミーだとわかるドキュメントが良い気がしています！
初学者が間違えて参考にしないように･･･。

絶対に試作中だとわかるように試作中-docsとか･･･？
あるいはまたいい感じになるまで @sevenc-nanashi さんのリポジトリとかでも良いかも。

（別の思惑などあればコメントください 🙏 ）

[sevenc-nanashi]

https://vitepress.dev/guide/extending-default-theme#layout-slots

サイトの一番上に固定メッセージも置けるっぽいです。
そこに「現在工事中です。（Issueへのリンク）」とでも書けば良さそう？

[sevenc-nanashi]

• wip_docsにして、
• ヘッダーに工事中の案内をつけて、
• いつものようにREADMEだけ作って自分のリポからPR

でやろうと思います。

[Hiroshiba]

そこに「現在工事中です。（Issueへのリンク）」とでも書けば良さそう？

たしかにレンダリングされた方も工事中だとわからないとダメですね！！
そういう感じで真っ赤に表示できると良さそう。
可能なら全ページの一番上にでかでかと表示できると嬉しいけど、テンプレート的なの作れなければまあタイトルだけでも。
あとmeta内にnoindexは指定しておきたみ。

wip_docsにして、
いつものようにREADMEだけ作って自分のリポからPR

方針賛成です！
あ、あまり変わらないけどWIP_docsとかにしていただけるとよりわかりやすいかも！

[sevenc-nanashi]

Initial CommitのPRを発射しました。