[Doc]Providing github pages on ascii-doc

[p0x0q]

概要

• zigenリポジトリ内にある./docs内に配置されているドキュメントをGitHub Pagesにて提供する。
• ドキュメント提供は，コミット時にGitHub Actionsを用いて，CI/CDでドキュメントページが自動生成されるようにする。

完成イメージ

• 提供されるドキュメントは，フォルダーの階層構造にならって，階層構造別に提供できるようにする。

▲ 実現例

実現方法

• actionsでadocをgithub pagesで表示可能なhtmlに変換してくれる機構を実現する手段はいくつかありそう。

1. https://ichi.pro/asciidoc-github-pages-github-actions-o-shiyoshite-kireina-html-dokyumento-o-jido-sakuseishite-hosutoshimasu-129235632602493
2. https://github.com/marketplace/actions/asciidoctor-ghpages

本案件の流れ

1. forkして@p0x0qのほうでCI/CDがzigenリポジトリで実現できる環境にする。
2. 完成し次第PR投げて見てもらう。
3. PR-Mergeで案件完了

その他

• その他，こういうの実現したいっていうのがあれば教えて下さい。

[p0x0q]

@Aki-7 ちょっと試しにやってみないとわからないと思うので，adocファイルの書き換えも想定して良いかな？

[Aki-7]

LGTM! 必要なものの全体像が見えてないので、運用してうちに変えたくなるかもだけど、とりあえずドキュメントをホストできるのが大事なので、いいと思います！ そういう段階なので、実装はできるだけシンプルな方法がいいとおもいます。

adocファイルの書き換えも想定して良いかな？

メタデータを書くとかかな？それなら全然いいと思う https://docs.asciidoctor.org/asciidoc/latest/document/metadata/

[p0x0q]

了解。ではシンプルにやってみる。 未踏書類関係で3/10以降になっちゃうかもだけど，やっておくわ～

[shierote]

@p0x0q ちなみにドメインは、初期設定だと zigen.github.io になる認識で良い？ htmlやcssのassetもこのrepoに置かれる形になる？

[p0x0q]

@shierote GitHub Pages的にはそうだね。DNSでCNAME使えば， http://ring_neo.p0x0q.com/ ↑上みたいにカスタムドメインも使える。

html, cssのアセットは，リポジトリはこのリポジトリでも，外でも可能じゃないかな。(自分が別プロジェクトで使ったときは内外対応してた）

実際に上のring_neoはprivateリポジトリのコミットをCI/CDで外部repoに出力結果を設置してる。 参考：https://github.com/RingTeam

[p0x0q]

カスタムドメイン使いたいとか，ドキュメントのassetファイルは外部リポジトリに置きたいとか，そういう要望がある感じかな？

[Aki-7]

直感ではドキュメントのためのCSSは基本このレポジトリには置きたくないかなー。

[p0x0q]

おけ，じゃあ以下のやつみたいに外部リポジトリに自動でコミットするようにすればいい感じか。 ひとまずミニマムでやってみて，そこらへんもできそうならやってみる。

どちらにせよ，特定のブランチ独占して使うことになるから，masterブランチ内の特定フォルダーにcssとかが配置されるという挙動にはならないと思う。

参考（特定のブランチにGitHub Pagesの内容だけ配置される形になっている）：https://github.com/RingTeam/ring_neo_web