天天看点
返回

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文件，具体的站点目录结构如下：

Maven生成项目站点(二)
Maven生成项目站点(二)

上面的例子展示了一些文件的位置，包含了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/" target="_blank" rel="external nofollow" 
			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" target="_blank" rel="external nofollow"  />
			<item name="Google" href="http://www.google.com" target="_blank" rel="external nofollow"  />
		</links>
		<!--配置站点导航链接-->
		<breadcrumbs>
			<item name="导航" href="index.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
			<item name="Doxia" href="http://maven.apache.org/doxia/index.html" target="_blank" rel="external nofollow"  />
		</breadcrumbs>

		<menu name="${project.name}">
			<item name="Introduction" href="index.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow" />
			<item name="News" href="news.html" target="_blank" rel="external nofollow" />
			<item name="Features" href="features.html" target="_blank" rel="external nofollow" />
			<item name="Installation" href="installation.html" target="_blank" rel="external nofollow" />
			<item name="Configuration" href="configuration.html" target="_blank" rel="external nofollow" />
			<item name="FAQ" href="faq.html" target="_blank" rel="external nofollow" />
			<!--菜单嵌套-->
			<item name="Developer Resources" href="/developer/index.html" target="_blank" rel="external nofollow"  collapse="true">
			<item name="System Architecture" href="/developer/architecture.html" target="_blank" rel="external nofollow" />
			<item name="Embedder's Guide" href="/developer/embedding.html" target="_blank" rel="external nofollow" />
			</item>
		</menu>
		<menu name="Documentation">
			<item name="Standard Usage" href="#.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
			<item name="Continuum Integration" href="#.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
		</menu>
		<menu name="Sample reports">
			<item name="Single project" href="#.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
			<item name="Multimodule projects" href="#.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
			<item name="Historic report" href="#.html" target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  target="_blank" rel="external nofollow"  />
		</menu>
		<menu name="Project Documentation">
			<item name="Project Information" href="project-info.html" target="_blank" rel="external nofollow"  />
			<item name="Project Reports" href="project-reports.html" target="_blank" rel="external nofollow"  />
		</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>[email protected]</email>
			<name>cruise</name>
			<organization>xjtu</organization>
			<roles>
				<role>softwareengineer</role>
			</roles>
			<timezone>8</timezone>
		</developer>
		<developer>
			<id>牛开复</id>
			<email>[email protected]</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
10.Maven site deploy 站点部署 Maven
上一篇: 【服务器部署系列-008】Linux 定时备份mysql数据文件到阿里云对象存储oss一、检查并安装定时任务二、编写脚本定时备份三天内的mysql数据
下一篇: Maven中deploy插件介绍

继续阅读