システム開発で思うところ

Javaで主にシステム開発をしながら思うところをツラツラを綴る

GitHubにMavenを使って作ったJavaDocを公開

はじめに

GitHubMavenリポジトリを作成して 細かくパッケージを分割した開発できるようになったと喜んでいたのですが パッケージを分けたためにJavaDocのリンクが切れてしまう状態になってしまいました。

vermeer.hatenablog.jp

リンク切れについてはモジュールとして まとめてJavaDocを生成すれば対応できます。

ただ、これだとローカル環境でコードから生成しないといけません。

まぁ、それでも良いのですが自分自身が利用者となった時、どこかにJavaDocが一か所で見られる状態になっていたら良いなぁと考えていくと JavaDocGitHubで公開したら良さそうだな、と。

ということで やってみたことの まとめです。

ざっくり

  • プロジェクトに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の概要の一番上に表示されるタイトルは デフォルトではartifactIdversionで自動で編集されます。

私の場合、現状では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ページ

vermeerlab API

たとえば、こんな感じでGitHubのトップREADMEに指定おけば JavaDocのURLやjarの場所が分かりやすいように思います*7

GitHub - vermeerlab/javadoc

さいごに

個人的にはOSSJavaDocもWeb上で見られるようにしてほしいなぁ、と。

GitHubだとMarkdownはWeb上で見られるので良いですが、API仕様まで確認したいときに ちょっと切なくなるんですよね。

「どんなAPI仕様なのかな?」くらいの気持ちで読みたい側からすると 地味に手間というか。。

ローカルでビルドすれば良いだけかもしれませんが、開発環境を介せず見られる方がありがたいです。

例えば、OSSAPI仕様を調べよう(確認しよう)と思ったときに できれば 検索エンジン経由でWeb上で見られると 楽というか。

イメージとしては JavaSEのAPI仕様は検索エンジンで引っかかってくれるので有難いですよね?という感じです。

今回のケースだとJavaPoetJavaDocGitHubに上げてくれているので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:というか、ファーストユーザーである自分にとって分かりやすい