aiscript
aiscript copied to clipboard
aiscript-dev
ちゃんとしたドキュメンテーションサイトを作る
Githubを直接見に行かせるのをやめたい AiScript Playgroundと統合させたドキュメンテーションサイトを作れるとよさそう
検討すべき点
- ドキュメンテーションサイトとして別リポジトリにするか？
- サイトとしての柔軟性は上がるが、ドキュメンテーションの更新をAiScript本体と併せてできない
- ドキュメンテーションはここにおいておいて別リポジトリとして参照する手もあるけどややこしい（こっちにpushされるたびにdocsリポジトリ側のsubmoduleを更新する or サイトのビルドWebhookを走らせる必要がある）
- ↑もしくは、Vitepressをdocsフォルダ内にインストールするか？
- ドキュメンテーションが同時に更新できるが、サイト自体の機能更新等もこのリポジトリで行うことになり若干煩雑になるかもしれない
- ドメインをどうするか？
- AiScriptがMisskeyの関連プロジェクトという位置づけなら
aiscript.misskey-hub.netとかでも良さそう（そのへんの位置づけを私はあんまり理解していない） - デプロイしたらもらえるドメイン系はなんか嫌（個人の感想です）
- AiScriptがMisskeyの関連プロジェクトという位置づけなら
こっちにpushされるたびにdocsリポジトリ側のsubmoduleを更新する or サイトのビルドWebhookを走らせる必要がある
これが自動化できるなら別リポジトリに分けたい気がします
じゃあドメインを取る or
github.ioなりpages.devなりの既定サブドメインを使うになるか・・・
個人的には既定サブドメインで十分かなと思います（Playgroundは今までそうだったし） Cloudflare Pagesのことはよく知らないのですが、Github Pagesと比べてどちらが良いとかあります？
Cloudflare Pagesのことはよく知らないのですが、Github Pagesと比べてどちらが良いとかあります？
SSRが出来るのとレイテンシが小さいぐらいだと思うので、ドキュメント置くだけなら変わらないと思います。
個人的には aiscript-dev/aiscript-dev.github.io リポジトリを作ってそこで管理するのが一番シンプルで良いかなと思いました。
サイトだけを別リポジトリにするとドキュメンテーションをpushするまでサイトがどのように見えるか確認できないから、 ドキュメンテーションごと別リポジトリにするか、このリポジトリでサイトジェネレータをインストールしたいです
mdBookだとコードブロックの実行とか設定できるのでいいかもしれないです
https://takejohn.github.io/aiscript-docs/ 試しに作ってみました 一部のコードブロックはボタンを押すと実行されるようになっています gettextを使って英語に対応していて、右上の地球アイコンから切り替えられます
ソース: https://github.com/takejohn/aiscript-docs
サイトだけを別リポジトリにするとドキュメンテーションをpushするまでサイトがどのように見えるか確認できないから、 ドキュメンテーションごと別リポジトリにするか、このリポジトリでサイトジェネレータをインストールしたいです
~~サイトジェネレータを独立のnpmパッケージ化して、aiscriptとaiscript-dev.github.ioで共用するようなことは可能ですか？~~ いやCargoのパッケージ（？）使ってるから難しそうだな…
~サイトジェネレータを独立のnpmパッケージ化して、aiscriptとaiscript-dev.github.ioで共用するようなことは可能ですか？~ いやCargoのパッケージ（？）使ってるから難しそうだな…
NAPI-RSとか使えば作れないことはないかも
それをわざわざ作ってメンテするくらいなら、aiscript-dev.github.ioなりのドキュメント用のリポジトリに全部持っていくほうが良いと思います。
とりあえずドキュメンテーションごと別リポジトリ化するのが楽そうなのでまずそっちでやって、
~サイトジェネレータを独立のnpmパッケージ化して、aiscriptとaiscript-dev.github.ioで共用するようなことは可能ですか？~ いやCargoのパッケージ（？）使ってるから難しそうだな…
NAPI-RSとか使えば作れないことはないかも
これができそうなら後からでも欲しいかも。（これまでのコードの変更とドキュメントの変更を同じPRで要求できてた仕組みはかなりプラスに働いていたように思うので）
一応VitePressでPlayground的なことをやるやつも作ってみました https://github.com/kakkokari-gtyih/aiscript-docs-vp
一応VitePressでPlayground的なことをやるやつも作ってみました https://github.com/kakkokari-gtyih/aiscript-docs-vp
ここではVue.jsの:知見:がある人が多いと思うからそっちのほうがよさそう :+1:
一応vitepressのほうは一通りできたと思うのですが、
- mdbook or vitepress or その他、どれを使うか
- docsの運用場所（このrepoに入れる or 別で運用する or その他）などの運用面
はどうしましょう？
私は勝手にvitepress周りの整備をやっただけなので他の皆さんにおまかせするつもりですが
とりあえず
https://aiscript-dev.github.io/ja/ https://github.com/aiscript-dev/aiscript-dev.github.io
1点お願いですがライセンスの明示をしてほしいです 🙏
何でライセンスすべきか分からなかったので敢えて保留にしていたのですが普通にMITでよさそうですかね？
https://aiscript-dev.github.io/ja/ https://github.com/aiscript-dev/aiscript-dev.github.io
docsとtranslationsフォルダーにあるものは消してしまっていいと思います。 どちらを見ればいいのかと混乱させてしまうことが考えられるので あと、READMEのリンクは書き換えが必要ですね
長いこと公式のドキュメントがGitHubにしかなかった事でリンクが向いてると思うので、誘導用のdocs/README.mdとかくらいあったほうがいいかもしれない