AVAJAVA Web Tutorials

A 'site' is the standard way that a mavenSW project is documented. Typically, a src/site directory is created, and a site.xml file in this directory describes the layout of the site documentation. Other documentation files are included in various directories within the site directory. When a "mvn site" command is performed, these various files are processed, and a documentation 'site' is generated in the project's target directory.

The archetype:create goal of the maven archetype plugin can be used to add simple site files to a pre-existing project. This can be a useful way to get you started with some basic files (site.xml and index.apt) that you can use to start generating site documentation. I created an EclipseSW external tool configuration to do this from Eclipse, shown below. The ${maven_exec} string substitution variable points to my maven mvn.bat file (C:\dev\apache-maven-2.0.8\bin\mvn.bat). The working directory is set to my Eclipse workspace directory. The groupId and artifactId of the project in question need to be entered via string prompts. In addition, notice the -DarchetypeArtifactId=maven-archetype-site-simple parameter.

The configuration is shown here:

I'm going to add the simple site files to my "aproject" project, shown here. This project has a groupId of 'com.maventest' and an artifactId of 'aproject'.

I selected the "mvn archetype~create site simple" external tool to execute it.

When prompted for a groupId, I entered 'com.maventest'.

When prompted for an artifactId, I entered 'aproject'.

The console output from the execution of the external tool configuration is shown here:

Console output from 'mvn archetype:create -DgroupId=com.maventest -DartifactId=aproject -DarchetypeArtifactId=maven-archetype-site-simple'

[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:create] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[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] [archetype:create]
[INFO] Defaulting package to group ID: com.maventest
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating Archetype: maven-archetype-site-simple:RELEASE
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.maventest
[INFO] Parameter: packageName, Value: com.maventest
[INFO] Parameter: package, Value: com.maventest
[INFO] Parameter: artifactId, Value: aproject
[INFO] Parameter: basedir, Value: C:\dev\workspace
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] ********************* End of debug info from resources from generated POM ***********************
[INFO] Archetype created in dir: C:\dev\workspace\aproject
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Sun Feb 17 03:56:37 PST 2008
[INFO] Final Memory: 5M/9M
[INFO] ------------------------------------------------------------------------

When the maven goal has completed, we can see that a src/site directory was created in the project, and we can see that the directory contains a site.xml file and an apt directory that contains an index.apt file.

I can now start adding documentation to the project using these template files.