Maven Site Plugin is a very useful mechanism used to generate some basic information, such as the Javadoc, project and module descriptions, dependencies, and management tools, for the project.
Maven Site Plugin provides a fine-grained way to customize the final outcome using the APT language. In this section, we will learn how to produce a basic site, grabbing information from the pom.xml file and the source code of our project and avoiding extra documentation. In the last paragraph, we will customize a module to provide more information.
To create a site easily, we first choose a directory for a sample project using the following archetype:
$ mvn archetype:create -DgroupId=org.sonatype.mavenbook -DartifactId=sample-project
This archetype creates a simple project named sample-project:
Then, we run the following command:
$ mvn site
The preceding command will create a target/site folder.
To see the result, open the index.html file or connect to the http://localhost:8080/ URL after running the following command:
$ mvn site:run
Maven will use the default configuration to create the site.
Now, we are ready to customize the site for our multimodule project structure.
Open the pom.xml file of transportation-project and add the following plugin in the reporting element:
[…]
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
<reportSets>
<reportSet>
<reports>
<report>index</report>
<report>dependencies</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
[…]Use the following command line to run the goal:
$ mvn clean install site
The install command is required if it is not already installed. Maven will create the target/site folder, including our HTML pages, one site for each submodule. Opening the index.html file, you should get a result as shown in the following screenshot:
The transportation project's index page
Unfortunately, we cannot navigate the site correctly. To explore each submodule, we must deploy the site into the final deploy directory.
We can simply define the deploy directory by creating a new property named siteDirectory:
[…]
<properties>
<siteDirectory>C://siteDirectory</siteDirectory>
</properties>
[…]After we define the property, we have to set the distributionManagement element, as shown in the following snippet:
[…]
<distributionManagement>
<site>
<id>transportation-site</id>
<url>file://${siteDirectory}</url>
</site>
</distributionManagement>
[…]The url tag describes the deploy location. It's possible to save it into both a local and remote directory (at the moment, only SSH is supported).
Now, we can deploy the site running the following command:
$ mvn site:deploy
Maven should produce the following result:
[INFO] ------------------------------------------------------------------ [INFO] Building transportation-statistics-batch-jar 0.0.1 [INFO] ------------------------------------------------------------------ [INFO] [INFO] --- maven-site-plugin:3.3:deploy (default-cli) @ transportation-statistics-batch-jar --- file://C://siteDirectory/ - Session: Opened [INFO] Pushing C:\WSSites ransportation-project ransportation- statistics-batch-jar argetsite [INFO] >>> to file://C://siteDirectory/transportation-statistics-batch-jar file://C://siteDirectory/ - Session: Disconnecting file://C://siteDirectory/ - Session: Disconnected [INFO] ------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] [INFO] transportation-project ................ SUCCESS [ 1.268 s] [INFO] transportation-common-jar ................ SUCCESS [ 0.357 s] [INFO] transportation-acq-ejb ................ SUCCESS [ 0.264 s] [INFO] transportation-acq-war ................. SUCCESS [ 0.217 s] [INFO] transportation-acq-ear .................. SUCCESS [ 0.340 s] […]
It's also possible to define other interesting reports by editing maven-project-info-reports-plugin and adding the highlighted reports:
[…]
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
<reportSets>
<reportSet>
<reports>
<report>index</report>
<report>dependencies</report>
<report>project-team</report>
<report>cim</report>
<report>issue-tracking</report>
<report>scm</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
[…]Let's further explore the reports we added in the POM snippet previously.
First, we can define the project team by adding the following code at the project root of our pom.xml file:
<project …>
[…]
<developers>
<developer>
<id>ucicero</id>
<name>Umberto Cicero</name>
<email>[email protected]</email>
<organization>MyOrganization</organization>
<roles>
<role>book-author</role>
<role>developer</role>
</roles>
</developer>
</developers>
[…]The cim report is the Continuous Integration Management (CIM) system based on triggers or timings such as Hudson CI (see Chapter 5, Continuous Integration and Delivery with Maven).
We can configure the cim report using the ciManagement element given here:
[…]
<ciManagement>
<system>Hudson CI</system>
<url>http:// localhost:8080/</url>
<notifiers>
<notifier>
<type>mail</type>
<address>[email protected]</address>
</notifier>
</notifiers>
</ciManagement>
[…]To carry out information on issue management, it's possible to set our issue tracker, such as JIRA
or MantisBT. Set the issueManagement element as follows:
[…] <issueManagement> <system>MantisBT</system> <url>http://localhost/mantisbt</url> </issueManagement> […]
Finally, we can define scm or Source Code Management (SCM). It is used to provide information related to the code management system in order to maintain the project in the code repository (check SVN, GIT, CVS, Mercurial, and so on, in Chapter 5, Continuous Integration and Delivery with Maven). To configure SCM, include the following code in the pom.xml file:
[…]
<scm>
<connection>
scm:svn:https://my-scm-host/trunk/project/
</connection>
<developerConnection>
scm:svn:https://my-scm-host/trunk/project/
</developerConnection>
<url>https://my-scm-host/trunk/project </url>
</scm>
[…]We are finally ready to rebuild our project's site and deploy it. Just run the following compact command:
$ mvn clean site:site site:deploy
The following screenshot shows the team's project.html page:
The project's team page
This configuration is the same for each module of the project since it is inherited from the parent POM.
In this section, we'll see how to configure a site for a single submodule. We chose the transportation-acq-ear module as an example.
First, we open the pom.xml file of transportation-acq-ear, and then add a new person at project-team:
[…]
<developers>
<developer>
<id>ucicero</id>
<name>Umberto Cicero</name>
<email>[email protected]</email>
<organization>MyOrganization</organization>
<roles>
<role>book-author</role>
<role>developer</role>
</roles>
</developer>
<developer>
<id>gveneri</id>
<name>Giacomo Veneri</name>
<email>[email protected]</email>
<organization>HisOrganization</organization>
<roles>
<role>book-author</role>
<role>developer</role>
<role>tester</role>
</roles>
</developer>
</developers>
[…]Run the following command again:
$ mvn clean site:site site:deploy
The following screenshot shows a different team for the transportation-acq-ear module as a result of our operation:
The transportation-acq-ear's project team
It is also possible to publish the Javadoc on the generated site through Javadoc Plugin. Add the following snippet in the reporting element of the pom.xml file of our multimodule project:
<project>
[…]
<reporting>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<reportSets>
<reportSet>
<reports>
<report>javadoc</report>
<report>test-javadoc</report>
</reports>
</reportSet>
<reportSet>
<id>aggregate</id>
<inherited>false</inherited>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
[…]
</reporting>
[…]
</project>The aggregate directive tells Maven to aggregate the Javadoc of each module on a global directory. The highlighted code, <report>test-javadoc</report>, requires the processing of the Javadoc for the test code.
Execute the following command:
$ mvn clean site:site site:deploy
We should see a result like this:
[…] [INFO] >>> maven-javadoc-plugin:2.9:javadoc (report:javadoc) > generate-sources @ transportation-reporting-ear >>> [INFO] [INFO] <<< maven-javadoc-plugin:2.9:javadoc (report:javadoc) < generate-sources @ transportation-reporting-ear <<< [INFO] [INFO] >>> maven-javadoc-plugin:2.9:test-javadoc (report:test-javadoc) > generat e-test-sources @ transportation-reporting-ear >>> [INFO] [INFO] --- maven-ear-plugin:2.8:generate-application-xml (default-generate-appli cation-xml) @ transportation-reporting-ear --- [INFO] Generating application.xml [INFO]
Maven will create a new item on the site's menu, linking it to the Javadoc:
The Javadoc link
Clicking on the link, you will see a result like this:
The Javadoc result
If you don't like the classic Maven site skin, or if you want a more charming template, Maven provides you with the possibility of customizing it. All we have to do is create the following directory in our project:
Create an XML file named site.xml inside the directory. To customize our site, we will use Skin (Maven Fluido Skin), which is included by default in the site plugin. Other available Skins are:
- Maven Application Skin
- Maven Classic Skin
- Maven Default Skin
- Maven Stylus Skin
Define the site.xml file as follows:
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Maven"
xmlns="http://maven.apache.org/DECORATION/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0
http://maven.apache.org/xsd/decoration-1.0.0.xsd">
<bannerLeft>
<name>A Maven Site</name>
<src>
http://ww1.prweb.com/prfiles/2011/10/26/9257737/gI_61351_Packt%20Publishing%20logo.PNG
</src>
<href>http://www.packtpub.com/</href>
</bannerLeft>
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>1.3.1</version>
</skin>
<custom>
<fluidoSkin>
<sideBarEnabled>true</sideBarEnabled>
<googlePlusOne />
</fluidoSkin>
</custom>
<body>
<links>
<item name="packtpub" href="http://www.packtpub.com/"/>
</links>
<menu name="Regular Web Site">
<item name="APT Format"
href="http://maven.apache.org/doxia/references/apt-format.html"/>
<item name="Xdoc Example" href="xdoc.html"/>
<item name="FAQ" href="faq.html"/>
</menu>
<menu ref="reports"/>
<footer>Packt. All rights reserved.</footer>
</body>
</project>If we run the following command, we will get a site that has a new (and very cool) look:
$ mvn clean site:site site:deploy
The following is an example of a site with a new look:
The transportation project site with maven-fluido-skin
Maven Site Plugin supports an easy way to provide additional details about the project. Customizing the main page of each submodule is very easy; we only need to write a few text lines.
Maven Site Plugin allows us to write content in different languages. In our example, we will use Almost Plain Text (APT). Navigate to the directory shown in the following screenshot:
Create a simple text file named index.apt that contains the following data; take care to preserve the same indentation:
------
Title: transportation-acq-ear
------
transportation-acq-ear
This component acquires information from:
* android
* Onboard Unit Device
* Technology
** Java
Java is ...
** Maven
Maven is ..Now, copy the site.xml file that was previously defined in the folder shown in the following screenshot:
Finally, run the following command:
$ mvn clean site:site site:deploy
The resulting index page will look as follows:
Custom index transportation-project-acq-ear