概要
- gendocはD言語標準の方法でドキュメント生成するためのヘルパツールです
- dubプロジェクトのフォルダで
dub run gendocすればインストール不要で誰でも簡単に使えます - dlang-jpのCookbookで使うために作りました！
D言語のドキュメント生成事情
2018年にまとめたのでご参照
2018年に標準の方法について「訓練されていなければ困難」と書きました。
この理由たらしめている課題は、「標準の方法の使用方法」でしれっと端折っている、1つのソースコードから1つのHTMLしか吐けない点と、デフォルトのスタイルが貧弱という点、dubを使っている場合に-Iで指定しなきゃいけないインポートディレクトリを探すのが大変な点などです。
このため、ほかの多くのツールが作られました。
しかしながら、それら多くのツールは、D言語のコンパイラでドキュメントを生成させるのではなく、どうせやるなら自分でドキュメントの抽出やパースをしてしまおうという思想のものがほとんどでした。
さて、dlang-jpというコミュニティがあります。D言語もくもく会というイベントの参加メンバーが懇親会の場で思いついて今年夏ごろに始まったコミュニティです。
その場で「いろいろドキュメント生成見てみたけど、なんだかんだ公式のがほかの言語のドキュメント含め一番見やすくて強いよね」という話が挙がりました。
公式のドキュメントは、D言語コンパイラで生成したHTMLファイルによってできています。しかしながらこれを自分で作るプロジェクトでやろうとしたときの問題点は先述のとおりです。
Cookbookみたいな、コードサンプル集ほしいよねという話もあり、先述の課題を何とかしようという流れになったので、そういうヘルパツールを作りました。
gendoc
ダウンロード・インストールは不要です。
使い方は、以下のようにあなたの持っているdubプロジェクトでコマンドを実行するだけです。
dub run gendoc
これでdubがgendocをダウンロード・ビルド・実行してくれます。
カスタマイズ
生成されるHTMLの外観や動作を変えたい場合は、以下のようにコマンドを実行することで、デフォルトのテンプレがdubプロジェクトのファイルに追加されます。
dub build gendoc -c=init
追加された、(dub project)/ddocや(dub project)/source_docsの*.ddocや*.dd, *.css, *.jsなどを編集することで、生成されるページを任意にカスタマイズできます。
ツールがやってくれること
このツールがやってくれることは、以下の通り。
- dubプロジェクトから依存関係を調べて、dmdやldc2でコンパイルするために
-Iで指定するべきインポートディレクトリを探します。 - dubプロジェクトで管理されているソースファイルの一覧を使って、モジュールリストを作ります。(メニューとかに使う)
-
*.mustacheなファイルを使って内部情報を埋め込みます。(バージョン情報とか) -
*.ddocのように一緒にコンパイルするファイルを探します。(デフォルトではddocから) -
*.css,*.jsなど、装飾になど他に使用するファイルを探してコピーします。(デフォルトではsource_docsから) -
*.dや*.ddファイルに対してdmdかldc2コンパイラを呼び出してHTMLを生成します
ダウンロード・インストール不要の理由
dubパッケージとして登録しているため、dub run gendocとすると、dubがオンラインから勝手に探してダウンロード・ビルド・実行してくれます。
また、装飾用のファイルはデフォルトでは現在のディレクトリを起点に探しますが、それが見つからなければバイナリファイルのある所(つまりdubがビルドした場所)を起点に探し、使ってくれるという寸法です。
ただし、注意点があって、これを一回やると、バージョンがその時のものに固定されてしまう場合があるようで、gendocのバージョンが更新されても勝手に追従してくれません。(dubのバグ)
dub remove gendocとか、パッケージのキャッシュを保存しておく場所にあるgendoc用のフォルダを直接消し去るとかすると新しいバージョンに追従できると思います。
隘路事項
dubプロジェクトの情報を使うので、dubをライブラリとして使用しています。ライブラリとしての使用方法は、「ソース読め」だったのでその点苦労しました。
dubの中身は難解だともっぱらのうわさです。
しかもバグバグしい挙動をいくつか見つけてしまい、それを回避するのも苦労しました。
また、コンパイラは、通常のアプリケーションやライブラリをビルドする場合であればいっぺんにソースファイルを渡してあげればすべて一緒にコンパイル・リンクしてくれるのですが、HTMLファイルはファイル名がかぶるファイルがあるといっぺんに指定することができません。 ※ちなみにこれ、解決すると$50もらえますよ
そのため、できる場合はいっぺんにコンパイルして時短。できない場合はファイルを一つずつコンパイルするみたいなことをやってます。
サンプルページ
開発に貢献
- https://github.com/shoo/gendoc
- バグ報告はこちら
- プルリクエスト歓迎します！
- Cookbookのレイアウト上の問題や要望も、最終的にはこのツールに取り込まれることが多いです。
- 使ってくれるたびにdubパッケージのダウンロード数がカウントされるので、作者のやる気がでます！