はじめに
GitHubにMavenリポジトリを作成して 細かくパッケージを分割した開発できるようになったと喜んでいたのですが パッケージを分けたためにJavaDocのリンクが切れてしまう状態になってしまいました。
vermeer.hatenablog.jp
リンク切れについてはモジュールとして まとめてJavaDocを生成すれば対応できます。
ただ、これだとローカル環境でコードから生成しないといけません。
まぁ、それでも良いのですが自分自身が利用者となった時、どこかにJavaDocが一か所で見られる状態になっていたら良いなぁと考えていくと JavaDocもGitHubで公開したら良さそうだな、と。
ということで やってみたことの まとめです。
ざっくり
- プロジェクトに
docsフォルダを作成する（maven）
- ついでにオフライン環境でも使えるようにjarも作る（maven）
- ドキュメントを作成する（maven）
docsフォルダに格納されている資産をソースとしたgh-pagesを作成する（GitHub）
対象をまとめる
ローカル環境のプロジェクトのドキュメントを作成するプロジェクトからの相対位置を指定します。
<modules>
<module>../base</module>
<module>../xml</module>
</modules>
モジュールをまとめてJavaDocを作成するための指定です。
<aggregate>true</aggregate>
ただ作るだけだったら何もしなくていいのですが、せっかくなので ちょっとした整形をしてみようと思います。
タイトルをつける
JavaDocの概要の一番上に表示されるタイトルは デフォルトではartifactIdとversionで自動で編集されます。
私の場合、現状ではWeb上で公開する資産は最新のものだけを と思ったので タイトルを固定した表現にしようと思いました。
ついでにWindowのタイトルも一致させました。
<doctitle>${javadoc.title}</doctitle>
<windowtitle>${javadoc.title}</windowtitle>
概要・詳細を編集
package-infoのようなドキュメントをトップページに記載することで 全体の概要もしくは詳細の説明が記載されているリンクへの誘導を表現できます。
ドキュメント用のhtmlを作成します*1。
/src/main/javadoc/overview.html
今回はmevenプロジェクトへのリンクを指定することで READMEページへ誘導する、という趣旨の編集をしました。
JavaDocと同様に、１行目が概要、２行目以降が説明として出力されます。
外部プロジェクトのドキュメントのリンク
自分のプロジェクトへのリンクはmodulesで参照すれば良いですが、外部プロジェクトの場合は公開されているリンク先を指定します。
<links>
<link>https://docs.oracle.com/javase/jp/8/docs/api</link>
<link>https://square.github.io/javapoet/javadoc/javapoet</link>
</links>
私は日本人なので、JavaSEのドキュメントも日本語の方が読みやすいです。
ということで、日本語の公開ドキュメントへのリンクにしました。
JavaPoet*2
も参照しているので、それも追記しました*3。
FastClasspathScanner*4も使用していますが、JavaDocとしては表現されることはないので除外しています。*5
パッケージをグループ化
フラットなJavaDocは読みにくいので意味のある塊でまとめて表現すると良いと思います*6。
<groups>
<group>
<title>Annotation Processor Core</title>
<packages>org.vermeerlab.apt*</packages>
</group>
<group>
<title>Annotation Processer with JavaPoet</title>
<packages>org.vermeerlab.apt.element:org.vermeerlab.apt.javapoet</packages>
</group>
<group>
<title>Annotation Processor Command</title>
<packages>org.vermeerlab.apt.command.*</packages>
</group>
</groups>
ドキュメントの出力先を指定
デフォルトのままだとtarget配下にJavaDocが作成されて資産管理対象外のままになってしまうということと、GitHubPageで参照するフォルダに常に作成されるようにしておきたい ということで出力先のパスを指定します。
<destDir>docs</destDir>
GitHubPageではdocs配下の資産を自動でgh-pageの対象資産としてくれます。
デフォルトではJavaDocにタイムスタンプを埋め込むため、常にすべての資産が更新対象になってしまいます。
ということでタイムスタンプを除去する設定をしました。
<notimestamp>true</notimestamp>
ローカル環境用のjarの出力先
ドキュメントと同様、デフォルトのままだとtarget配下に作成されるので 出力先を変更します。
<jarOutputDirectory>jar</jarOutputDirectory>
フォルダ名 jar に作成します。
コマンド実行
mvn clean:clean javadoc:aggregate-jar
参考にしたリンク通りなので・・
2016年新機能! GitHubのmasterブランチをWebページとして公開する手順 - Qiita
vermeerlab API
たとえば、こんな感じでGitHubのトップREADMEに指定おけば JavaDocのURLやjarの場所が分かりやすいように思います*7。
GitHub - vermeerlab/javadoc
さいごに
個人的にはOSSのJavaDocもWeb上で見られるようにしてほしいなぁ、と。
GitHubだとMarkdownはWeb上で見られるので良いですが、API仕様まで確認したいときに ちょっと切なくなるんですよね。
「どんなAPI仕様なのかな？」くらいの気持ちで読みたい側からすると 地味に手間というか。。
ローカルでビルドすれば良いだけかもしれませんが、開発環境を介せず見られる方がありがたいです。
例えば、OSSのAPI仕様を調べよう（確認しよう）と思ったときに できれば 検索エンジン経由でWeb上で見られると 楽というか。
イメージとしては JavaSEのAPI仕様は検索エンジンで引っかかってくれるので有難いですよね？という感じです。
今回のケースだとJavaPoetはJavaDocもGitHubに上げてくれているのでJavaDocがイイ感じに作成できました。
そういうメリットもあります。
