Maven生成项目站点(二)

上一篇文章介绍了如何在Maven下生成一个简单的站点，显然这样的站点不能满足大家的项目需求。本篇将介绍如何通过自定义站点来丰富项目信息，完成站点定制。mvn site功能强大，特别是在生成的项目站点中可以添加很多测试报告及文档。

一、如果不做任何配置，执行mvn site命令生成默认样式的站点，主要包括以下内容：

1、子模块列表Modules；

2、文档列表Project Documentation，主要有两大块：项目信息Project Information 、项目报告Project Reports；

3、项目信息Project Information，默认包括项目相关概要信息、持续集成、依赖、插件、配置库等报告，详见官网（Apache > Maven > Plugins > Maven Project Info Reports Plugin）：

http://maven.apache.org/plugins/maven-project-info-reports-plugin/

4、项目报告Project Reports，取决与pom.xml文件中<reporting>部分的配置，可集成checkstyle、cobertura、Findbugs等报告；

二、定制站点一般需要解决3个问题：

1、如何定制站点的内容和样式？

2、mvn site生成的文件分布在各子模块目录下，如何统一管理？

3、如何将报告发布成站点，以便于项目组其它成员通过浏览器能够方便的查看？

三、站点目录结构

Maven将所有的站点文档放在src/site目录下。同格式的文档则被放在其子目录下。所有的APT文档应该放到src/site/apt下，所有的FML文档应该被放到src/site/fml下，所有的XDoc文档应该被放到src/site/xdoc下。站点描述符是文件src/site/site.xml，所有的资源应该存储在src/site/resources。Maven Site插件构建web站点的时候，它会从资源目录复制所有文件至站点的根目录。如果你存储了一个文件src/site/resources/images/test.png，那么你就能够在你的站点文档中使用相对路径images/test.png引用该图片。

1.想要增加站点内容，或者减少项目信息报告，则需要建立site.xml文件，修改项目pom文件，具体的站点目录结构如下：

上面的例子展示了一些文件的位置，包含了APT, FML, HTML, XHTML, 和XDoc。注意XHTML内容直接存放在src/site/resources目录。architecture.html文件不会被Doxia处理，它会被直接复制到输出目录，如果你想要包含不被处理的HTML内容，你可以使用这种方式，而不使用Doxia和Maven Site插件的模板和格式化功能。

四.编写项目文档

Maven使用一个叫做Doxia的文档处理引擎，它读取多个资源格式至一个一般的文档模型。Doxia之后就可以处理文档并渲染结果至不同的输出格式，如PDF或者XHTML。要编写你项目的文档，你需要基于能被Doxia解析的格式编写内容。Doxia现在支持Almost
Plain Text (APT), XDoc (一种Maven1的文档格式), XHTML, 和 FML (对FAQ文档很有用) 格式。

具体的格式编写见官方文档：

• APT： http://maven.apache.org/doxia/references/apt-format.html
• FML： http://maven.apache.org/doxia/references/fml-format.html
• XDoc： http://maven.apache.org/doxia/references/xdoc-format.html

下面给出一个具体的apt示例

aptdom.apt

      -----------------             Title:Apt Text            -----------------             Author:cruise            -----------------             Date:2013-12-05            ------------------      Paragraph 1, line 1.\  Paragraph 1, line 2.  Paragraph 2, line 1.\  Paragraph 2, line 2.Section title* Sub-section title** Sub-sub-section title*** Sub-sub-sub-section title**** Sub-sub-sub-sub-section title      * List item 1.      * List item 2.        Paragraph contained in list item 2.            * Sub-list item 1.            * Sub-list item 2.      * List item 3.        Force end of list:      []+------------------------------------------+Verbatim text not contained in list item 3+------------------------------------------+      [[1]] Numbered item 1.                [[A]] Numbered item A.                [[B]] Numbered item B.      [[2]] Numbered item 2.  List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]].      [Defined term 1] of definition list.      [Defined term 2] of definition list.+------------------------------------------------------------+<plugin>  <groupId>org.apache.maven.plugins</groupId>  <artifactId>maven-site-plugin</artifactId>  <version>3.2</version>  <dependencies>    <dependency>      <groupId>org.apache.maven.doxia</groupId>      <artifactId>doxia-module-markdown</artifactId>      <version>1.3</version>    </dependency>  </dependencies></plugin>+------------------------------------------------------------+  --- instead of +-- suppresses the box around verbatim text.[images/gallery.jpg] Figure caption*----------*--------------+----------------:| Centered | Left-aligned | Right-aligned  || cell 1,1 | cell 1,2     | cell 1,3       |*----------*--------------+----------------:| cell 2,1 | cell 2,2     | cell 2,3       |*----------*--------------+----------------:Table caption  No grid, no caption:*-----*------*------* cell | cell | hello*-----*------*------* cell | cell | hello*-----*------*------*  Horizontal line:=======================================================================New page.  <Italic> font. <<Bold>> font. <<<Monospaced>>> font.  {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.  Link to {{{anchor}showing alternate text}}.  Link to {{{http://www.pixware.fr}Pixware home page}}.  Force line\  break.  Non\ breaking\ space.  Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.  Copyright symbol: \251, \xA9, \u00a9.~~Commented out.

五.自定义站点外观

1）在site.xml文件中配置站点描述，从而改变站点的外观，具体参看官网：

http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html

下面给出一个具体的示例：

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/DECORATION/1.4.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/DECORATION/1.4.0 http://maven.apache.org/xsd/decoration-1.4.0.xsd"name="Account Email"><bannerLeft><name>Project Name</name><src>images/banner-left.png</src><width>300</width><height>80</height><href>http://maven.apache.org/</href><border>2</border></bannerLeft><bannerRight><name>bannerRight image</name><src>images/banner-right.png</src><height>80</height><width>200</width><href>http://www.google.com</href><border>2</border></bannerRight><publishDate position="right" format="yyyy-MM-dd" /><version position="left" /><poweredBy><logo name="Maven" href="http://maven.apache.org/"img="http://maven.apache.org/images/logos/build-by-maven-black.png" /></poweredBy><!--配置站点皮肤--><skin><groupId>org.apache.maven.skins</groupId><artifactId>maven-classic-skin</artifactId><version>1.0</version></skin><body><head /><links><item name="Maven" href="http://maven.apache.org" /><item name="Google" href="http://www.google.com" /></links><!--配置站点导航链接--><breadcrumbs><item name="导航" href="index.html" /><item name="Doxia" href="http://maven.apache.org/doxia/index.html" /></breadcrumbs><menu name="${project.name}"><item name="Introduction" href="index.html"/><item name="News" href="news.html"/><item name="Features" href="features.html"/><item name="Installation" href="installation.html"/><item name="Configuration" href="configuration.html"/><item name="FAQ" href="faq.html"/><!--菜单嵌套--><item name="Developer Resources" href="/developer/index.html" collapse="true"><item name="System Architecture" href="/developer/architecture.html"/><item name="Embedder's Guide" href="/developer/embedding.html"/></item></menu><menu name="Documentation"><item name="Standard Usage" href="#.html" /><item name="Continuum Integration" href="#.html" /></menu><menu name="Sample reports"><item name="Single project" href="#.html" /><item name="Multimodule projects" href="#.html" /><item name="Historic report" href="#.html" /></menu><menu name="Project Documentation"><item name="Project Information" href="project-info.html" /><item name="Project Reports" href="project-reports.html" /></menu><menu ref="reports"/></body><custom><fluidoSkin><topBarEnabled>true</topBarEnabled><sideBarEnabled>true</sideBarEnabled></fluidoSkin></custom></project>

2)创建自定义的主题CSS

最简单的影响项目web站点外观和感觉的方法是使用项目的site.css。就像你为站点提供 的任何图片或XHTML内容一样，site.css也被包含src/site/resources/css目录中。在src/site/resources/images中放入站点需要要到的图像资源。

3）完成上面的定制之后，下面开始对POM文件进行配置来定制项目报告

A:配置项目依赖插件

<plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><source>1.5</source><target>1.5</target></configuration></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-resources-plugin</artifactId><configuration><encoding>UTF-8</encoding></configuration></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-site-plugin</artifactId><version>3.2</version><dependencies><!-- 生成html的依赖jar包 --><dependency><groupId>org.apache.maven.doxia</groupId><artifactId>doxia-module-markdown</artifactId><version>1.3</version></dependency><!-- 添加对ssh/scp的支持 --><dependency><groupId>org.apache.maven.wagon</groupId><artifactId>wagon-ssh</artifactId><version>1.0</version></dependency></dependencies><configuration><!-- 配置站点国际化 --><locales>zh_CN</locales><!-- 输出编码 --><outputEncoding>GBK</outputEncoding></configuration></plugin></plugins>

 B:配置项目报告

<!-- 配置项目报告 --><reporting><plugins><!-- 无需配置Project Info Reports Plugin即默认包含所有Project Information报告 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-project-info-reports-plugin</artifactId><version>2.4</version><configuration><dependencyDetailsEnabled>false</dependencyDetailsEnabled><dependencyLocationsEnabled>false</dependencyLocationsEnabled></configuration><!-- simpler configuration without reportSets available for usual cases --><reportSets><reportSet><reports><!-- index一定要生成,否则链接问题 --><report>index</report><report>dependencies</report><report>project-team</report><report>issue-tracking</report><report>license</report><report>scm</report><report>cim</report><report>modules</report><report>plugins</report><report>help</report><report>summary</report></reports></reportSet></reportSets></plugin><!-- 使用dashboard插件来生成全局报告 --><plugin><groupId>org.codehaus.mojo</groupId><artifactId>dashboard-maven-plugin</artifactId><version>1.0.0-beta-1</version><configuration><encoding>UTF-8</encoding></configuration></plugin><!-- 代码更改日志 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-changelog-plugin</artifactId><version>2.1</version></plugin><!--生成javadoc文档的插件 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-javadoc-plugin</artifactId><version>2.7</version></plugin><!--检查代码规范的插件 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-checkstyle-plugin</artifactId><version>2.5</version><configuration><!-- 使用maven社区代码风格 --><configLocation>config/maven_checks.xml</configLocation></configuration></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-report-plugin</artifactId><version>2.4.3</version></plugin><plugin><!-- 代码隐藏bug检查 --><groupId>org.apache.maven.plugins</groupId><artifactId>maven-pmd-plugin</artifactId><version>3.0</version><configuration><!-- 多模块聚合 --><aggregate>true</aggregate></configuration></plugin><!-- 生成站点文件具体信息报告 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-linkcheck-plugin</artifactId><version>1.1</version></plugin><!-- 在web页面展现源码 --><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-jxr-plugin</artifactId><version>2.3</version><configuration><!-- 多模块聚合 --><aggregate>true</aggregate></configuration></plugin><!-- 测试覆盖率 --><plugin><groupId>org.codehaus.mojo</groupId><artifactId>cobertura-maven-plugin</artifactId><version>2.5.2</version></plugin><!-- 项目还需要做的TODO报告 --><plugin><groupId>org.codehaus.mojo</groupId><artifactId>taglist-maven-plugin</artifactId><version>2.4</version></plugin><plugin><groupId>org.codehaus.mojo</groupId><artifactId>findbugs-maven-plugin</artifactId><version>2.5.3</version></plugin></plugins></reporting>

C:配置项目信息报告

        <!-- 问题解决信息 --><issueManagement><system>Linux</system><url>http://www.baidu.com/</url></issueManagement><!-- 持续集成信息 --><ciManagement><url>http://127.0.0.1:8080/hudson</url><system>Hudson</system></ciManagement><!-- 开发人员信息 --><developers><developer><id>cruise</id><email>[e-mail]</email><name>cruise</name><organization>xjtu</organization><roles><role>softwareengineer</role></roles><timezone>8</timezone></developer><developer><id>牛开复</id><email>[e-mail]</email><name>牛开复</name><organization>xjtu</organization><roles><role>架构师</role></roles><timezone>8</timezone></developer></developers><!--许可证 --><licenses><license><url>http://127.0.0.1:8080/LICENSE.txt</url><comments>评论</comments><name>完全开源</name></license></licenses><scm><connection>scm:svn:http://127.0.0.1/svn/my-project</connection><developerConnection>scm:svn:https://127.0.0.1/svn/my-project</developerConnection><tag>HEAD</tag><url>http://127.0.0.1/websvn/my-project</url></scm>

D:国际化支持（注意项目采用UTF-8编码格式）

<properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding></properties>

E:部署站点

<distributionManagement><!-- <site> <id>www.yourcompany.com</id> <url>file:///site/projectname</url> </site> --><site><id>account-email.website</id><name>My website</name><url>scp://129.1.12.8/home/maven/deploy/site</url></site></distributionManagement>

六.完成POM的配置后，接下来将站点发布到HTTP server

首先，需要得到站点发布地址的服务器信息，修改~/.m/settings.xml文件，配置server信息：

<server>      <id>account-email.website</id>      <username>root</username>      <password>root</password>      <filePermissions>664</filePermissions>      <directoryPermissions>775</directoryPermissions></server>

id：HTTP server 的id。username, password：用于登陆此服务器的用户名和密码。

七.正确的配置完成上述内容，接下来即可输入命令让Maven来部署站点了

$mvn clean site-deploy