PlantUMLダイアグラムのハイパーリンク追加

[koriym]

要約

PlantUMLダイアグラムの出力形式を現在のPNGからSVGに変更し、SVGダイアグラム内にハイパーリンクを追加する機能をリクエストします。これにより、クラス図からGitHub上の対応するソースコードファイルにリンクできるようになり、使い勝手が大幅に向上すると思います。

背景

現在、PlantUMLはクラス図をPNG形式で視覚化しています。しかし、大規模なコードベースを扱う場合、ダイアグラムのクラスをクリックしてGitHubリポジトリ内のソースコードに直接移動できる機能があると便利です。ハイパーリンクを実現するためにPNG形式でなく、SVG形式のダイアグラムが必要です。SVGはベクタ形式であり、拡大縮小しても品質が劣化しないしサイズや速度のメリットもあります。

提案

SVG形式のサポート: PlantUMLダイアグラムの出力形式としてSVGをサポートします。
ハイパーリンクのサポート: SVGダイアグラム内にハイパーリンクを追加できるようにします。
GitHubとの統合: これらのハイパーリンクがGitHubリポジトリ内の特定のファイルおよびコード行を指すことができるようにします。

Alice -> Bob: Authentication Request [[https://github.com/your-repo/auth_request.code]]
Bob --> Alice: Authentication Response [[https://github.com/your-repo/auth_response.code]]

例

@startuml
skinparam svgLinkTarget _blank

class User {
    +String name
    +String email
+    [[https://github.com/your-repo/your-project/blob/main/src/User.php User Class]]
}

class Account {
    +int accountNumber
    +double balance
+    [[https://github.com/your-repo/your-project/blob/main/src/Account.php Account Class]]
}

User --> Account
@enduml

＊ 矢印にはメソッドをリンクするといいかも知れません。

利点まとめ

• ナビゲーションの向上: ユーザーはダイアグラムから関連するコードセクションにすばやく移動できます。
• ドキュメントの強化: ダイアグラムがより情報豊かで実用的になります。
• 生産性の向上: 特に大規模なプロジェクトでクラス定義を探す時間を削減します。。
• 品質の向上: SVGはベクタ形式であるため、拡大縮小しても品質が劣化せず、視認性が高い。

参考

https://alps-asd.github.io/app-state-diagram/todomvc/index.html

インラインリンクですが、ノードとリンクがそれぞれの詳細情報にリンクされています。

ご検討のほどよろしくお願いいたします！

[smeghead]

@koriym
私自身が php-class-diagram で出力したスクリプトを PlantUMLを使ってPNG画像に変換するのが主な用途でした。そのため、SVGのリンクを付与できる機能を知りませんでした。確かにGithub Pagesに埋め込むクラス図の場合、リンクの埋め込み可能なSVG形式の方が利便性が高いのは納得です。

対応方針

php-class-diagram本体と、アクション(php-class-diagram-gh-action)のそれぞれで、以下のような対応を行なおうと考えています。

php-class-diagram の対応

1. 新規オプション --svg-toplink-url の追加。解析対象ののディレクトリのURLを指定します。
2. 上のオプションが指定されていた場合は、リンクを埋め込みます。最初は、リンクを埋め込む対象をリンクのみにします。リンクを指定する文字列も結構な容量になりそうなので

アクション(php-class-diagram-gh-action)の対応

1. Input の output-path の拡張子により、PNG形式とSVG形式を判定して PlantUML の -t オプションを適切に指定できるようにします。

この機能が実現できたら、1.3.0 としてリリースしたいと考えています。
とても良い提案を頂きありがとうございます。

[koriym]

これは私自身が全く同じ経験をしていまして、ある時、graphvizで出力する巨大なダイアグラムPNG画像がメモリ不足で描画できなくなってしまったのです。サイズを減らすためには .... SVG ?....SVGってもしかしてハイパーメディア？　リンクできる？？ ...おおできる！これは便利というかSVGはあんな古いフォーマットなのに素晴らしいな、そもそもベクター画像を生成するのにPNGがいいところってある？？ ... そんなプロセスでした。（長い間、PNGで出力していましたがもうダイアグラムをPNGで出力することはなくなってしまいました）

SVGはリンクできるだけでなく、小さく、高速で、美しいです！

[koriym]

提案です。

新規オプション --svg-toplink-url の追加。解析対象ののディレクトリのURLを指定します

問題ないと思うのですが --gh-repo=user/package 指定ができれば簡単で可読性も良いような気もします。gitlabとかもあるので自由にセットできるのも必要でしょうがご検討ください。

[smeghead]

@koriym
--svg-toplink-url は、曖昧な記憶で書いてしまったので、意図と違ってしまっていました。

skinparam topurl https://plantuml.com/

--svg-topurl にしようと考えてました。出力形式がsvgの時だけ使われるオプションである事を表しつつ、PlantUMLのskinparamの名前に準えて名前を付けました。
一般用途のためにこのパラメータを残しつつ、Github専用の可読性が高いパラメータ(--svg-gh-repo=user/package)も用意するのはどうでしょうか？

[koriym]

PlantUML の設定オプションで、topurlという図にURLを表示すオプションがあるんですね。

確かに現在はsvgでのみこのURLがハイパーリンクとしてユーザーが使うことができますが、もしかしたら将来PDFもリンクができるようになるかも知れないし、そもそもUML自体がリンクを持つということは（自身がどのコードを示しているかという）自己説明がつきより豊かなドキュメントになると思います。（その時、全体の一つだけリンクを持つのと各クラスがリンクするパターンがあり、今回の提案が後者です）

その理由もなくても、私はコンテキストを含んだ短い名前を好みますが、ここは設計者の @smeghead さんの好みや方針でもちろん問題ないです！蛇足かもですが、どういう見方をするか、もしかしたら興味を持ってもらえるかもと思って長々と書いてしまいました。😀

[smeghead]

ありがとうございます。
はい、対象の捉え方として興味深いお話でした。
PNG形式の場合は出力するPlantUMLスクリプトの容量を抑えておきたいという意図から、svgというプレフィックスを付ける方向で考えています。もちろん再考する可能性もあります。
実装の方向性は見えてきましたので、実装を進めてみます。

[smeghead]

@koriym
リンク付きのSVGを出力するGHアクションが動作するようになりました。

php-class-diagram(本体)の対応

• --svg-topurl オプションの追加

本体側ではGithubを意識する必要がないため、Github用のパラメータの追加は不要と判断しました。

php-class-diagram-gh-action(GHアクション) の対応

• target-repo パラメータの追加
• target-branch パラメータの追加

output-path に svg拡張子のファイルを指定することと、この2つのパラメータを指定することにより、リンク付きのSVGを出力するようになります。

      - name: Create class diagram
        id: create-class-diagram
        uses: smeghead/php-class-diagram-gh-action@v0
        with:
          target-path: src/DiagramElement
          output-path: php-class-diagram.svg
          target-repo: ${{ github.repository }}
          target-branch: ${{ github.ref_name }}

https://github.com/smeghead/php-class-diagram/actions/runs/9338785125
php-class-diagramのリポジトリに設定したGithub ActionsのワークフローのArtifactsで、生成されたSVGファイルが確認できます。

GHアクションのREADMEに追加したパラメータの記述を記載しました。
https://github.com/smeghead/php-class-diagram-gh-action

[koriym]

@smeghead Congratulation! 🎉
やはりサイズも小さくていいですね。

[koriym]

Ray.Aopのダイアグラムをを作成してみました。
https://koriym.github.io/Ray.Aop/php-class-diagram.svg