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:
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:
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:
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:
Clicking on the link, you will see a result like this:
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:
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:
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: