maven2のsiteゴールで自作ページを追加する

maven2のsiteゴールは,標準Webページや各種レポートの出力により,プロジェクトの情報共有を行うためのWebページを簡単に生成することができる。もちろんこれだけでも十分魅力的なのだが,特にオープンソースなライブラリなどを開発するプロジェクトであれば,そのライブラリの使用方法やチュートリアル,ダウンロードページなどを追加して,siteゴールのみでコンテンツ全てを賄いたくなってくるだろう。今回は,siteゴールで自作のWebページを追加する方法を紹介しようと思う。

まずは,siteゴールを提供してくれるmaven-site-pluginプラグインについて,日本語を使用できるように設定しておく必要がある。もちろん自作のWebページは日本語で記述したいだろうから,ほとんどの場合この設定は必須となるだろう。

org.apache.maven.plugins

maven-site-plugin

ja

UTF-8

UTF-8

siteゴールで適用されるロケールをja,入出力されるコンテンツの文字コードをUTF-8と設定している。実はこれだけで,標準Webページに関しては日本語化される。

maven-site-ja.jpg

siteゴールで出力されるコンテンツは,実はsite.xmlファイルを作成することで制御することができる。site.xmlファイルを工夫することにより,出力されるコンテンツに対して,様々なカスタマイズを施すことが可能だ。もちろん,今回の「自作ページを追加する」という目標を達成するためにも,site.xmlファイルが必要となる。site.xmlファイルは,src/siteディレクトリに作成する。

site.xmlファイルは,XML形式のテキストファイルである。以下に例を示してみよう。

version=”1.0” encoding=”UTF-8”?

${reports}

body要素の中にmenu要素が記述されている。menu要素を使用することにより,siteゴールで出力される左側のメニューについて,自作のメニューを追加することができるのだ。上記の例では,「Hello!」というメニューを追加し,item要素を更に定義することによって,「User Guide」というメニュー項目を追加している。「User Guide」メニュー項目はリンクとなり,その飛び先はhref属性で指定されているuserguide.htmlファイルとなる。

標準Webページおよび各種レポートを出力する場所は「${reports}」で示す。上記では,自作メニューの下に出力するよう指示がされた状態である。

この時点でsiteゴールを実行すると,出力結果は以下のようになる。自作のメニューが追加されていることがわかるだろう。

maven-site-mymenuitem.jpg

さて,href属性で指定したuserguide.htmlファイルだが,これを作成するための方法として,4種類存在する。

  • site/resourcesディレクトリ内にuserguide.htmlファイルを作成する。

  • site/aptディレクトリ内にuserguide.aptファイルを作成する。

  • site/xdocディレクトリ内にuserguide.xmlファイルを作成する。

  • site/fmlディレクトリ内にuserguide.fmlファイルを作成する。

resourcesディレクトリに作成する方法は,ページ全体をuserguide.htmlファイルで全て記述する必要があるので,siteゴールが出力するヘッダや左のメニューを使わないページにしたいときに採用する。つまり,標準Webページのようなページにしたい場合は,この方法を選択すべきではない。

xdocディレクトリに作成する方法は,自作したいページをXDoc形式で記述したい場合に採用する。これは,文書構造を決められたタグセットを使ってXML形式で記述していく形態となる。XDoc形式で書かれたファイルは, こんな感じになる。XML大好きな人には,これがお勧め。

fmlディレクトリに作成する方法は,自作したいページがFAQのページな場合に採用する。これは,FAQに特化した文書構造を,XDoc形式と同じように,決められたタグセットを使ってXML形式で記述する。fml形式で書かれたファイルは, こんな感じになる。

最後に紹介するaptディレクトリに作成する方法が,僕の個人的なお勧めである。この方法では,自作したいページをAPT形式(Almost Plain Text)で記述する。APT形式は,Wikiでページを記述するときの文法に似ている。どのような形式なのかは,Mavenサイトの「 Guide to the APT Format」に例と共に詳しく載っているので,参考にして欲しい。今回の例でいけば,以下のような感じだ。


Hello User Guide Page —— Yoichiro Tanaka —— 2007/02/19 使い方 HelloBeanは,messageプロパティを持つクラスです。 このクラスは,JavaBeans仕様に則っています。そのため, 以下のようなことが実現できます。

  • 直列化することができる。
  • MVC1およびMVC2のモデル(M)として利用可能。 利用例 HelloBeanは以下のようにして利用可能です。
  • Javaコード内 +——————————————————+ HelloBean bean = new HelloBean(); bean.setMessage(“Hello World!”); +——————————————————+

上記の内容を,userguide.aptというファイル名でsite/aptディレクトリに保存する。この際,文字コードをUTF-8にしておく必要があるので,お忘れなく。その後,siteゴールを実行して,出力されたWebページの左のメニューから「User Guide」リンクをクリックすれば,APT形式で書かれた内容がめでたくHTML形式に変換されて,しかも標準Webページと同じレイアウトで出力されているのが確認できるだろう。

maven-site-mypage.jpg

まとめると,

  • site.xmlにメニュー項目を追加する。

  • APT形式でページを記述してsite/aptディレクトリに保存する。

  • siteゴールを実行する

の繰り返しで,maven2によるプロジェクトのWebページを手軽に追加していくことができる。思ったよりも手軽に自分なりのプロジェクトサイトを作ることが可能である。

APT形式で書かれたファイルの中にマルチバイト文字が含まれていても,maven-site-pluginプラグインに対する文字コード指定が行われていて,尚且つAPT形式のファイルがUTF-8であれば,正しく日本語ページを出力することができる。しかし残念なことに,site.xmlファイルにマルチバイト文字を記述しても,どうしても文字化けしてしまう。つまり,メニューに日本語が使えないことを意味している。これは,maven-site-pluginが国際化について非常に中途半端な対応になってしまっていることが原因で,最近リリースされたmaven2.0.5でも修正されていない。

ま,メニューに日本語が使えなくても,ほとんど支障はないだろう。maven2のsiteゴールは,それだけでもmaven2の採用理由になるくらい,非常に重要なゴールである。標準Webページ,各種レポート,そして自作ページの追加といった機構をうまく利用して,プロジェクトの成功を確かなものにして欲しい。

このエントリーをはてなブックマークに追加

関連記事

2023年のRemap

Remapにファームウェアビルド機能を追加しました

Google I/O 2023でのウェブ関連のトピック

2022年を振り返って

現在のRemapと今後のRemapについて