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


Page:    1 2 >

We can add javadocs to our mavenSW site documentation for a project by adding the Maven Javadoc Plugin to the reporting section of the project's pom.xml file. An example of this is shown here.

reporting section of pom.xml

	<reporting>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-javadoc-plugin</artifactId>
				<configuration>
					<links>
						<link>http://commons.apache.org/lang/api</link>
						<link>http://java.sun.com/j2se/1.5.0/docs/api</link>
						<link>http://this-one-will-not-work</link>
					</links>
				</configuration>
			</plugin>
		</plugins>
	</reporting>

The configuration section for the maven-javadoc-plugin is optional. I used "links" to specify javadoc links to other libraries. In the above example, the link to http://commons.apache.org/lang/api means that javadoc references to classes in commons-lang (such as StringUtils) will show up as links to those classes. The link to http://java.sun.com/j2se/1.5.0/docs/api will result in links to the Sun site for API docs for classes such as String. The link to http://this-one-will-not-work is an example of a bad link to an external library.

My complete project pom.xml file is shown here. It includes some code to do a site-deploy to ApacheSW webdav.

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.maventest</groupId>
	<artifactId>aproject</artifactId>
	<packaging>jar</packaging>
	<version>1.0-SNAPSHOT</version>
	<name>aproject</name>
	<url>http://maven.apache.org</url>
	<dependencies>
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>commons-lang</groupId>
			<artifactId>commons-lang</artifactId>
			<version>2.3</version>
			<scope>compile</scope>
		</dependency>
	</dependencies>
	<build>
		<extensions>
			<!-- start - for deploying using webdav -->
			<extension>
				<groupId>org.apache.maven.wagon</groupId>
				<artifactId>wagon-webdav</artifactId>
				<version>1.0-beta-2</version>
			</extension>
			<!-- end - for deploying using webdav -->
		</extensions>
	</build>
	<distributionManagement>
		<!-- start - location where site is deployed - username/password for site.deployments in server.xml -->
		<site>
			<id>site.deployments</id>
			<name>Site deployments</name>
			<url>dav:http://192.168.1.7/sites/${artifactId}/</url>
		</site>
		<!-- end - location where site is deployed - username/password for site.deployments in server.xml -->
	</distributionManagement>
	<reporting>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-javadoc-plugin</artifactId>
				<configuration>
					<links>
						<link>http://commons.apache.org/lang/api</link>
						<link>http://java.sun.com/j2se/1.5.0/docs/api</link>
						<link>http://this-one-will-not-work</link>
					</links>
				</configuration>
			</plugin>
		</plugins>
	</reporting>
</project>

To build the site documentation but not deploy it, we can do:

mvn clean site

However, I'd like to build and deploy the site, so I'll do a:

mvn clean site-deploy

This command generates the following console output:

Console output for 'mvn clean site-deploy' on 'aproject' project

[INFO] Scanning for projects...
WAGON_VERSION: 1.0-beta-2
[INFO] ------------------------------------------------------------------------
[INFO] Building aproject
[INFO]    task-segment: [clean, site-deploy]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory C:\dev\workspace\aproject\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] ************************************************************** 
[INFO] Starting Jakarta Velocity v1.4
[INFO] RuntimeInstance initializing.
[INFO] Default Properties File: org\apache\velocity\runtime\defaults\velocity.properties
[INFO] Default ResourceManager initializing. (class org.apache.velocity.runtime.resource.ResourceManagerImpl)
[INFO] Resource Loader Instantiated: org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader
[INFO] ClasspathResourceLoader : initialization starting.
[INFO] ClasspathResourceLoader : initialization complete.
[INFO] ResourceCache : initialized. (class org.apache.velocity.runtime.resource.ResourceCacheImpl)
[INFO] Default ResourceManager initialization complete.
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Literal
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Macro
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Parse
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Include
[INFO] Loaded System Directive: org.apache.velocity.runtime.directive.Foreach
[INFO] Created: 20 parsers.
[INFO] Velocimacro : initialization starting.
[INFO] Velocimacro : adding VMs from VM library template : VM_global_library.vm
[ERROR] ResourceManager : unable to find resource 'VM_global_library.vm' in any resource loader.
[INFO] Velocimacro : error using  VM library template VM_global_library.vm : org.apache.velocity.exception.ResourceNotFoundException: Unable to find resource 'VM_global_library.vm'
[INFO] Velocimacro :  VM library template macro registration complete.
[INFO] Velocimacro : allowInline = true : VMs can be defined inline in templates
[INFO] Velocimacro : allowInlineToOverride = false : VMs defined inline may NOT replace previous VM definitions
[INFO] Velocimacro : allowInlineLocal = false : VMs defined inline will be  global in scope if allowed.
[INFO] Velocimacro : initialization complete.
[INFO] Velocity successfully started.
[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] Preparing javadoc:javadoc
[INFO] ------------------------------------------------------------------------
[INFO] Building aproject
[INFO] ------------------------------------------------------------------------
[INFO] No goals needed for project - skipping
[INFO] Preparing javadoc:test-javadoc
[INFO] ------------------------------------------------------------------------
[INFO] Building aproject
[INFO] ------------------------------------------------------------------------
[INFO] No goals needed for project - skipping
[INFO] [site:site]
[INFO] Generating "JavaDocs" report.
[ERROR] Error fetching link: http://this-one-will-not-work/package-list. IGNORED IT.
Loading source files for package com.maventest...
Constructing Javadoc information...
Standard Doclet version 1.6.0_04
Building tree for all the packages and classes...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\App.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\Howdy.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\package-frame.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\package-summary.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\package-tree.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\constant-values.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\class-use\Howdy.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\class-use\App.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\com/maventest/\package-use.html...
Building index for all the packages and classes...
Generating C:/dev/workspace/aproject/target/site/apidocs\overview-tree.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\index-all.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\deprecated-list.html...
Building index for all classes...
Generating C:/dev/workspace/aproject/target/site/apidocs\allclasses-frame.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\allclasses-noframe.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\index.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\help-doc.html...
Generating C:/dev/workspace/aproject/target/site/apidocs\stylesheet.css...
[INFO] Generating "Test JavaDocs" report.
[ERROR] Error fetching link: http://this-one-will-not-work/package-list. IGNORED IT.
Loading source files for package com.maventest...
Constructing Javadoc information...
Standard Doclet version 1.6.0_04
Building tree for all the packages and classes...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\AppTest.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\package-frame.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\package-summary.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\package-tree.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\constant-values.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\class-use\AppTest.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\com/maventest/\package-use.html...
Building index for all the packages and classes...
Generating C:/dev/workspace/aproject/target/site/testapidocs\overview-tree.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\index-all.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\deprecated-list.html...
Building index for all classes...
Generating C:/dev/workspace/aproject/target/site/testapidocs\allclasses-frame.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\allclasses-noframe.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\index.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\help-doc.html...
Generating C:/dev/workspace/aproject/target/site/testapidocs\stylesheet.css...
[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] [site:deploy]
http://192.168.1.7/sites/aproject/ - Session: Opened  
Uploading: ./apidocs/allclasses-frame.html to http://192.168.1.7/sites/aproject/

#
Transfer finished. 932 bytes copied in 0.011 seconds
Uploading: ./apidocs/allclasses-noframe.html to http://192.168.1.7/sites/aproject/

...SECTION REMOVED FOR THE SAKE OF CLARITY...

#
Transfer finished. 57 bytes copied in 0.01 seconds
Uploading: ./testapidocs/stylesheet.css to http://192.168.1.7/sites/aproject/

#
Transfer finished. 1420 bytes copied in 0.0090 seconds
http://192.168.1.7/sites/aproject/ - Session: Disconnecting  
http://192.168.1.7/sites/aproject/ - Session: Disconnected
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 14 seconds
[INFO] Finished at: Fri Feb 22 05:19:52 PST 2008
[INFO] Final Memory: 18M/34M
[INFO] ------------------------------------------------------------------------

In the console output, notice the following:

[ERROR] Error fetching link: http://this-one-will-not-work/package-list. IGNORED IT.

This link didn't work, which we expected. We did not see error messages to our links to the JavaSW 1.5 API and Commons LangS API docs, so these worked correctly.

(Continued on page 2)

Page:    1 2 >


Related Tutorials: