「tblsで出したER図をGitHub Pagesに出したいな〜〜！の砂場」というレポジトリを作って遊んでました。
「(学習・実装面で)低コスト」「(実用性の面で)ほどほどに十分」という方法を探っていたのですが、概ね満たしたと思います。満足。
場面設定
ER図をいい感じに！！っていうのはk1LoWさんが解決してくれているので、その先の話。
qiita.com
(↓の資料、改めて読んだけどやっぱり良いので凄い。もっと使い込みたいな・・)
The future of tbls and "Documentation as Code" / phpconfuk 2023 - Speaker Deck
「MarkdownだからGitHub上ですごく簡単に見られる」というのが嬉しく、継続的にドキュメントを管理(更新＆利用)していくのを強力に支援してくれるな〜と思いつつ、
「自動生成されたものをGit管理するとコンフリクトしてしまうのう*1」「かといってmainに対して自動pushもなぁ」って事も稀にあり*2。
「mainにマージしない・Git管理下におかない」&&「必要なタイミングでリアルタイムに最新化される」&&「すぐに見ようっていう気持ちを妨げないくらい簡単に開ける」をやっていきたいな〜〜
っていう場面です。
支援してくれた技術
昔・・・って書いていて「どのくらい前の話だっけ？」と思いますけど、
かつてのGitHub Pagesは「専用のブランチが必要」「パブリックなページしか作れない」だったので。
これが、今だと「(ブランチは用意せずに)actionsで更新できる」「プライベートでも使える」になっているので、機運を感じた次第
やったこと
1,3は何も問題なくて「ただそのまま」って感じで、2に関しては actions/jekyll-build-pages に面倒を見てもらうようにしました。
結果
最終的にこういうworkflowに。 github.com
https://o0h.github.io/tbls-gh-pages/ な感じでドキュメントが見られるようになったのでした。
思ったこと
シンプルな道具の組み合わせだけで実現できたのは利点が色々とありそう〜って感じがします。
- Table Definitionのサマリータグ＋コードブロックの所でマークアップが崩れている・・・っていうのが気になったけど、これは「tblsのテンプレートをいじる」とかでどうにかなりそう
- 「マークダウンを吐き出してくれる」「マークダウンをWebページに変換してくれる」という完全に相性の良い責務の分担と連携が出来ているので、双方の拡張性を妨げないで使えそう
- テンプレートをいじるっていう前提なら、Mermaidをいい感じにブラウザ表示するとかっていう手も使える
k1low.hatenablog.com - jekyllのテーマとかも変えられるね、うれしいね
最初は「Pandocもactionsでめっちゃ便利に使えるじゃん、最高〜〜！」ってことで、こっちでやろうかとも思ったんですが
「正しく.mdファイルを列挙する」「ドキュメント内の参照(hrefタグ)も適切にいじる」って、やりたくないね・・・？などと考えてぐったりしました。
今回の用途とは相性悪そうだなーと。でも、楽しそうだからいつか何かで使ってみたくはある。
もっとやれそうなこと
「コミットさせない」 = 「差分をとれなくなる」って事なので、コレはどうにかしたいですよね。
最新の定義をGitHubのartifactsとして上げておいて、必要なタイミングで取得 → tbls diff の結果を吐かせる！とか出来ると良さそう。
スキーマ管理しているディレクトリに変更があった場合に、そのPRにdiffを貼るとかなぁ
