Using Maven to Build a Web Site for Your Java Project
December 23, 2016
When creating a library for other developers to use it’s a huge help to provide documentation on how to add the library to a project and use it.
Building a site from scratch can take time and energy you don’t have, but if you’re using Maven that time and energy can be minimized by using the built-in site
lifecycle.
In this tutorial we will:
- use the
site
lifecycle to build a web site for a Java project - try out a couple of different “skins” for the web site
- create a custom About page to describe how to include and use the library
- generate JavaDocs as part of the web site
Initializing a Maven Project
If you don’t already have a project that you need to build a site for you can use Maven to quickly initialize a new project and try it out.
$ mvn archetype:generate -DgroupId=org.spilth -DartifactId=test -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
$ cd test
Building a Maven Project’s Site
To build a site for your Maven project, use the site
command. The site will be generated under target/site
.
$ mvn site
$ open target/site/index.html
It’s pretty bare bones but it’s a start!
Dealing with Warnings
You may have noticed some warnings in the output from the mvn site
command:
[WARNING] Report plugin org.apache.maven.plugins:maven-project-info-reports-plugin has an empty version.
[WARNING] It is highly recommended to fix these problems because they threaten the stability of your build.
[WARNING] For this reason, future Maven versions might no longer support building such malformed projects.
This is easy to fix. Add a <reporting>
section to your project’s pom.xml
and set the version for the maven-project-info-reports
plugin to 2.9
, the latest.
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.9</version>
</plugin>
</plugins>
</reporting>
Regenerate the site using mvn site
and the warnings should be gone.
Adding a Project Description
Currently there’s some placeholder text for the description of the project. You can fill this in by adding a <description>
element to your pom.xml
:
<project>
...
<name>test</name>
<url>http://spilth.org/test</url>
<description>Put the project description here</description>
...
</project>
Regenerate your project’s site and confirm the description shows up.
There are a number of additional elements you can add to your pom.xml
that will be turned into site information. Check out More Project Information in the POM Reference to see all the information you can provide.
Using the Fluido Skin
The default skin gets the job done but we can make things look a little nicer using the Maven Fluido Skin. All you need to do is create the file src/site/site.xml
with the following contents:
<project name="test">
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>1.5</version>
</skin>
</project>
I am specifically using the version 1.5 instead of the latest 1.6 because of an error it generates.
Regenerate the site and you’ll see something a bit more pleasing than the default Maven generated site.
Using the Reflow Skin
Fluido is based on Bootstrap 2 but there’s another skin based on Bootstrap 3 (that requires just a bit more configuration) called Reflow Maven Skin.
First, change your src/site/site.xml
to have the following contents:
<project name="test">
<skin>
<groupId>lt.velykis.maven.skins</groupId>
<artifactId>reflow-maven-skin</artifactId>
<version>1.1.1</version>
</skin>
<body>
<menu ref="reports"/>
</body>
</project>
Then update the <build>
section of your pom.xml
to add two dependencies required by Reflow to the maven-site
plugin.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.3</version>
<dependencies>
<dependency>
<groupId>lt.velykis.maven.skins</groupId>
<artifactId>reflow-velocity-tools</artifactId>
<version>1.1.1</version>
</dependency>
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity</artifactId>
<version>1.7</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
Regenerate the site and you’ll see a much more impressive looking site.
Reflow allows for a bunch of customization and options, so be sure to check out the Reflow configuration documentation.
Creating a Custom Index Page
Normally a Java project would now point you to its JavaDocs to learn how to use it but we can do better than that - showing users how to add and use your library will help them realize just how easy it is to use.
To accomplish this we’ll create a custom “About” page for the project. There are a few different markup languages you can use to do this but I highly recommend using Markdown.
Create the file src/site/markdown/index.md
and add some helpful introductory information. For a short example check out the index page for my piglib Java library.
Regenerate your site and you should see your new about page as the default.
Generating JavaDocs as Part of the Site
The About page can take a developer only so far. At some point they need to know the classes and methods that your library provides.
Add the following to the <reporting>
section of your pom.xml
and regenerate the site.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
</plugin>
Now the dropdown menu should include a Project Reports
link with a JavaDocs
link under it. Click on that and you’ll see your project’s JavaDocs.
Fixing JavaDocs Warnings
You may have once again noticed a warning from Maven when generating the JavaDocs. In fact, it shows up a few times:
[WARNING] Source files encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
This is another easy fix. In your pom.xml
add the following property:
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
Now when you regenerate the site you shouldn’t see any warnings. If you do, they’re likely regarding the JavaDocs for your classes and methods.
Improving your Project’s JavaDocs
Now is a good time to go through your project and make sure your classes have decent JavaDocs provided. At a minimum you want to give each class and method a description. Describing arguments, return values and throw exceptions will also help your users.
Publishing your Site
Once you’re happy with your About page and JavaDocs, it’s time to make your site public. I recommend using Codeship‘s Deployment feature to push the contents of target/site
to an Amazon S3 Bucket.