はじめに
GitHubにMavenリポジトリを作成して 細かくパッケージを分割した開発できるようになったと喜んでいたのですが パッケージを分けたためにJavaDocのリンクが切れてしまう状態になってしまいました。
リンク切れについてはモジュールとして まとめてJavaDocを生成すれば対応できます。
ただ、これだとローカル環境でコードから生成しないといけません。
まぁ、それでも良いのですが自分自身が利用者となった時、どこかにJavaDocが一か所で見られる状態になっていたら良いなぁと考えていくと JavaDocもGitHubで公開したら良さそうだな、と。
ということで やってみたことの まとめです。
ざっくり
- プロジェクトに
docs
フォルダを作成する(maven) - ついでにオフライン環境でも使えるようにjarも作る(maven)
- ドキュメントを作成する(maven)
docs
フォルダに格納されている資産をソースとしたgh-pages
を作成する(GitHub)
Maven
pom.xml
対象をまとめる
ローカル環境のプロジェクトのドキュメントを作成するプロジェクトからの相対位置を指定します。
<modules> <module>../base</module> <module>../xml</module> <!-- 省略 --> </modules>
モジュールをまとめてJavaDocを作成するための指定です。
<aggregate>true</aggregate>
JavaDocのための編集
ただ作るだけだったら何もしなくていいのですが、せっかくなので ちょっとした整形をしてみようと思います。
タイトルをつける
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と同様に、1行目が概要、2行目以降が説明として出力されます。
外部プロジェクトのドキュメントのリンク
自分のプロジェクトへのリンクは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
GitHub
参考にしたリンク通りなので・・
2016年新機能! GitHubのmasterブランチをWebページとして公開する手順 - Qiita
JavaDocページ
たとえば、こんな感じでGitHubのトップREADMEに指定おけば JavaDocのURLやjarの場所が分かりやすいように思います*7。
さいごに
個人的にはOSSのJavaDocもWeb上で見られるようにしてほしいなぁ、と。
GitHubだとMarkdownはWeb上で見られるので良いですが、API仕様まで確認したいときに ちょっと切なくなるんですよね。
「どんなAPI仕様なのかな?」くらいの気持ちで読みたい側からすると 地味に手間というか。。
ローカルでビルドすれば良いだけかもしれませんが、開発環境を介せず見られる方がありがたいです。
例えば、OSSのAPI仕様を調べよう(確認しよう)と思ったときに できれば 検索エンジン経由でWeb上で見られると 楽というか。
イメージとしては JavaSEのAPI仕様は検索エンジンで引っかかってくれるので有難いですよね?という感じです。
今回のケースだとJavaPoet
はJavaDocもGitHubに上げてくれているのでJavaDocがイイ感じに作成できました。
そういうメリットもあります。
*1:作成パスはデフォルト通り
*2:GitHub - square/javapoet: A Java API for generating .java source files.
*3:こちらのプロジェクトもGitHubPageでJavaDocを公開していますね
*4:GitHub - lukehutch/fast-classpath-scanner: Uber-fast, ultra-lightweight Java classpath scanner.
*5:追記してもmavenの実行時に警告が表示されるだけですが、警告が出るのが私は嫌なので外しました。安全を考えて警告が出ても追記しておくという運用でも良いと思います。
*6:JSR 376(Java9 Jigsaw)で また表現が変わってくるとは思いますが、Java8までだと有効だと思います
*7:というか、ファーストユーザーである自分にとって分かりやすい