はじめに
YAMLファイルを解析し、読みやすいHTMLドキュメントに変換するCLIツール ydock を開発しました。
npmパッケージとして公開しましたので、主な機能や使い方、そして開発の背景について紹介させていただきます。
作ったもの：ydock
ydock
https://github.com/wavecre8/ydock
既存のYAMLファイルから、モダンでインタラクティブなHTMLドキュメントを生成するツールです。
デモ
汎用的なYAMLファイル、CloudFormationテンプレート、AWS CLIの取得結果などが、見やすいHTMLドキュメントへと爆速で変換されます。
※ サンプルページは こちら から体験できます。
特徴
- 完全ローカルで完結: 解析とHTML生成はすべてローカル環境で実行され、機密情報を含むYAMLデータが外部に送信されることはありません。
- モダンなUI: インライン表示とツールチップ表示の切り替え、コンパクトビュー、各プロパティへのディープリンク、カラム幅やサイドバー幅のドラッグリサイズに対応しています。
-
モード切り替え:
generic（標準YAML用）とcfn（AWS CloudFormation用）の2モードをサポート。CloudFormationモードでは固有の組み込み関数やリソース参照を自然なドキュメント形式に変換します。 - 複数ファイルのマージ: 複数のYAMLファイルを1つのHTMLドキュメントにマージして出力できます。
- ポータルサイト: 複数ドキュメントを束ねるポータル画面を生成します。
カスタマイズ機能
ソースYAMLを一切編集せずに、補助ファイルを用意するだけで説明・表示名・非表示設定を付与できます。
1. ガイド機能：説明文のドッキング
ソースYAMLと同じ構造を持つガイドファイルを用意することで、自動的に説明文がドッキングされます。
- 部分定義で動作: すべてのキーを網羅する必要はありません。説明が必要な箇所だけを記述したミニマムなYAMLで動作します。
-
リンク機能:
[表示名](URL)記法により、ドキュメント内の他パラメータへの相互リンクや外部資料へのリンクを設定できます。
2. エイリアス機能：わかりやすい別名の設定
エイリアスファイルを定義することで、任意のキーに日本語などのわかりやすい表示名を設定できます。
システムが出力した英数字のキー名も直感的に把握できるようになります。
エイリアスファイルはドット区切りのフラットな構造で定義します。
# aliases/vpc.alias.yml
"Resources.MyVPC": "メインVPC"
"Resources.MyVPC.Properties.CidrBlock": "CIDRブロック"
"Resources.MyVPC.Properties.Tags[]": "リソースタグ"
配列の全要素に対して同じエイリアスを一括適用する場合は [] を使用します。
3. 除外機能：不要な要素の非表示
Excludeファイルを定義することで、ドキュメント出力に不要なプロパティや機密情報を含む項目を柔軟に非表示にできます。
4. スケルトン自動生成
YAMLファイルを解析し、上記3種の補助ファイルの雛形を自動生成する skeleton コマンドを用意しています。
手作業でYAML構造を書き起こす手間なく、すべての補助ファイルの雛形が一括生成されます。
ydock skeleton
-t オプションで特定の種類だけを生成することも可能です。
-
ydock skeleton -t guide: ガイドファイルのみ生成 -
ydock skeleton -t alias: エイリアスファイルのみ生成 -
ydock skeleton -t exclude: 除外ファイルのみ生成 -
ydock skeleton -t all: すべて生成。デフォルト動作です。
既存のファイルがある場合も、既存の定義を壊さずに不足している項目だけを安全に追記します。
使い方 Quick Start
インストールして使う場合
npm install -g @wavecre8/ydock
ydock init
ydock build
直接実行する場合
npx @wavecre8/ydock init
npx @wavecre8/ydock build
基本的な流れ
1. プロジェクトの初期化
ドキュメント化したいYAMLがあるディレクトリで初期化を実行します。
ydock init
# または npx @wavecre8/ydock init
設定ファイル setting.config.yml が生成されます。
2. 設定ファイルの編集
setting.config.yml を編集し、対象のYAMLファイルや各種ディレクトリを指定します。
lang: ja
guideDir: guides
aliasDir: aliases
excludeDir: excludes
index:
output: docs/index.html
title: ドキュメントポータル
groups:
- id: network
name: ネットワーク基盤
- id: compute
name: コンピュート基盤
pages:
- title: ネットワーク設計図
group: network
mode: cfn
sources:
- ./cloudformation/vpc.yml
output: ./docs/network.html
- title: サーバー設計図
group: compute
mode: cfn
sources:
- ./cloudformation/ec2.yml
output: ./docs/compute.html
index の groups にグループ識別子と名称を定義し、各ページの group にその識別子または名称を指定することで、ポータル画面上にグループごとのセクションやナビゲーションボタンが自動生成されます。グループ未指定のページはOtherグループへ自動的に集約されます。
指定したディレクトリに配置したファイルは、ソースファイル名に基づいて自動的に紐付けられます。
-
ガイドファイル:
{ソース名}.guide.yml例:vpc.guide.yml -
エイリアスファイル:
{ソース名}.alias.yml例:vpc.alias.yml -
除外ファイル:
{ソース名}.exclude.yml例:vpc.exclude.yml
3. 雛形ファイルの自動生成
ydock skeleton
# または npx @wavecre8/ydock skeleton
4. ビルド
ydock build
# または npx @wavecre8/ydock build
省略した場合はカレントディレクトリの setting.config.yml または setting.config.yaml が自動的に読み込まれます。
ファイルパスを指定する場合は -c オプションを使用します。
ydock build -c ./docs/setting.config.yml
--watch オプションを付けることで、ファイルの編集をリアルタイムに検知してブラウザを自動リロードするプレビュー環境も立ち上がります。
おわりに
もし気に入っていただけたら、GitHubでスターをいただけると開発の励みになります。
バグ報告や機能要望もIssueでお待ちしています。
使ってみた感想もコメントしていただけると嬉しいです。
Happy YAML Life!