mvn siteのtips三連発

この記事はJava Advent Calendar 2013の21日目として書かれたものです。昨日は@yoshioteradaさんの「Java EE 7 WebSocket アンチパターン」でした。

みなさん、mvn site使ってますか?

ドキュメントが自動生成できる!と思ってワクワクしながら実行するも、

  • 見た目がイマイチでテンション上がらなかったり
  • 大したドキュメントが生成されずにガッカリしたり
  • デプロイの設定が面倒でやらず、生成しても見なかったり

する事で有名なアイツです。やれば(pom.xmlをがっつり書けば)できる子なのに、初見でポイですよね。

そんなmvn siteですが、pom.xmlにちょっと化粧をしてやれば案外使いやすい場面もあるんです!今日はそんなTipsを3つほどご紹介しましょう。

スキンを使う

まず1つ目は、生成されるドキュメントのスキン(==テーマ)を変更して、見た目を華やかにしてみます。

デフォルトのスキンだとこのようなデザインになります。


イモっぽいデザインですねー。これを何とかしてみます。

Mavenのsiteプラグインにはアーティファクトを指定してスキンを差し替える機能があります。それをつかってもーちょい今風のスキンに差し替えてみましょう。Mavenのサイトにいくつかのスキンが用意されていますし、個人で作っている方もいらっしゃいます。今回はこのgreen-site-skinを使ってみます。

使い方はとても単純で設定をsrc/site/site.xmlに書くだけで済みます。

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <skin>
    <groupId>org.kathrynhuxtable.maven.skins</groupId>
    <artifactId>green-site-skin</artifactId>
    <version>1.1</version>
  </skin>

  <body>
    <menu ref="reports" />
    <menu ref="modules" />
  </body>
</project>

これでmvn siteを実行すると、見事スキンが適用されました。

スキンの作り方はこちらにまとめられているので、プロジェクトにあったスキンを作ってみるのも面白いかもしれません。

JAX-RS / JAXB / JPAのドキュメントを生成する

PMDやCPD、Checkstyleの結果などをドキュメントとして生成する方法は比較的知られていますが、JAX-RSやJAXB、JPAのアノテーションからjavadocを生成できるjax-docletというものをご存知でしょうか?2つ目はそいつをsiteのドキュメントに組み込む方法です。

jax-docletのサイトに書いてある通りpom.xmlを書くとAPIドキュメントが上書きされて読めなくなってしまうので以下のように書きましょう。

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <reportSets>
    <reportSet>
      <id>api</id>
      <reports>
        <report>javadoc</report>
      </reports>
    </reportSet>
    <reportSet>
      <id>jax-rs</id>
      <reports>
        <report>javadoc</report>
      </reports>
      <configuration>
        <doclet>com.lunatech.doclets.jax.jaxrs.JAXRSDoclet</doclet>
        <name>JAX-RSDocs</name>
        <destDir>jaxrsdoc</destDir>
        <docletArtifacts>
          <docletArtifact>
            <groupId>com.lunatech.jax-doclets</groupId>
            <artifactId>doclets</artifactId>
            <version>0.10.0</version>
          </docletArtifact>
        </docletArtifacts>
      </configuration>
    </reportSet>
  </reportSets>
</plugin>

6行目のレポートセットはAPIドキュメントの定義です。12行目のレポートセットでJAX-RSのドキュメントを生成しています。destDirを指定して、APIドキュメントが上書きされないようにする必要があります。

ちょっとの記述でRESTエンドポイントのドキュメントが一覧で見れるので結構便利なので是非お試しください。JAXBやJPAも同様の方法で出力できます。

siteをwarに突っ込む

3つ目は「site生成しても結局見ないしー」なアナタ。warにsiteを突っ込んじゃえばいいじゃない!という若干乱暴な方法をご紹介します。

ステップは2つ。まずsiteの出力をprepare-packageフェーズで行います。そしてwebリソースとしてwarに突っ込みます。

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.3</version>
  <executions>
    <execution>
      <id>attach-site</id>
      <phase>prepare-package</phase>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

このようにフェーズとゴールを指定して、warをパッケージングする前にsiteを生成させます。

そしてmaven-war-pluginを

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <version>2.4</version>
  <configuration>
    <webResources>
      <resource>
        <directory>${project.build.directory}/site</directory>
        <targetPath>site</targetPath>
      </resource>
    </webResources>
  </configuration>
</plugin>

このように書くことでsiteをパッケージに含める事ができます。このwarをデプロイしたらhttp://localhost:8080/siteで生成されたドキュメントを見ることができます。ちょっと楽ですね。

まとめ

使いどころがビミョーでなかなか使われてなさげなmvn siteですが、少し手をいれるだけで便利に使える機能がいっぱいあります。ぜひお試しください。

今回ご紹介した機能を使ったプロジェクトをこちらに用意してあります。生成したドキュメントはこちらです。それぞれ参考にしていただければと思います。

明日はKatsumi Kokuzawaさんです。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

次のHTML タグと属性が使えます: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>