How do I generate basic documentation for a project using maven site?
Author: Deron Eriksson
Description: This tutorial describes how to generate basic documentation for a project using maven site.
Tutorial created using: Windows Vista || JDK 1.6.0_04 || Eclipse Web Tools Platform 2.0.1 (Eclipse 3.3.1)


MavenSW has three lifecycles: clean, default, and site. The clean lifecycle, as its name suggests, it concerned with cleaning out the built resources from a project. Typically this is used to give the project a fresh, clean start before using mavenSW to build/package the project. The default lifecycle is concerned primarily with tasks such as building/packaging/installing/deploying the project. The site lifecycle is concerned with generating documentation for a project. This documentation takes the form of an HTML-based 'site', and this site can be deployed using the site lifecycle.

Generation of basic site documentation is extremely easy. To do so, we just need a maven command that calls the "site" phase, which by default is bound to the site:site goal. The generated site gets created in the project 'target' directory.

mvn site

In general, I've found it best to perform a "clean" prior to a "site" to ensure that the documentation is freshly generated.

mvn clean site

I created an EclipseSW External Tool Configuration for "mvn clean site":

External Tool Configuration for 'mvn clean site'

Here, I selected the "mytest" project and selected the "mvn clean site" external tool. This will perform a "mvn clean site" on the "mytest" project. Notice that there is no site directory present in the target directory prior to "mvn clean site".

Executing 'mvn clean site' on 'mytest' project

The "mvn clean site" executed on "mytest" generates the following console output. (Note that the first time "site" is run, a lot of jars are downloaded into the local maven repository. This is not shown here.)

Console output from 'mvn clean site'

[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building mytest
[INFO]    task-segment: [clean, site]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory C:\dev\workspace\mytest\target
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [site:site]
[INFO] Generating "Continuous Integration" report.
[INFO] Generating "Dependencies" report.
[INFO] Generating "Issue Tracking" report.
[INFO] Generating "Project License" report.
[INFO] Generating "Mailing Lists" report.
[INFO] Generating "About" report.
[INFO] Generating "Project Summary" report.
[INFO] Generating "Source Repository" report.
[INFO] Generating "Project Team" report.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 6 seconds
[INFO] Finished at: Tue Feb 05 10:14:10 PST 2008
[INFO] Final Memory: 13M/26M
[INFO] ------------------------------------------------------------------------

Above, notice that the clean:clean goal is bound to the clean phase, and the site:site goal is bound to the site phase.

After "mvn clean site", we can see that a site directory has been created in the target directory, and that it contains quite a bit of content.

site documentation has been created for project

The index.html page from the "mytest" site is shown below.

mytest project's index.html page

A tremendous amount of extremely useful information can be generated for a project with minimal effort. Maven site generation will be covered in much greater detail in later tutorials.


Related Tutorials: