This plug-in is used to generate the documentation site for your project. This includes both transforming your custom xdoc documents into XHTML (see the xdoc plugin), and running the designated reports for your project. The result is then packaged or deployed in the form that you desire.
To generate the site for your project, run:
maven site:site
The resulting site is created in target/docs (or whatever the
maven.docs.dest property is set to).
There are several alternatives for deploying and packaging the site.
If you would like to package a single redistributable version of the site,
you can create a J2EE WAR or an EAR using the goals site:war
or site:ear respectively. The site archive will be placed in
the target directory.
If you would like to deploy the site to a directory either locally or on a remote host, you can use:
maven site:deploy
From there, it can be served from a web server.
There are several different deployment mechanisms, which are listed in the table below.
You can use them by setting the maven.site.deploy.method property appropriately,
or by running the given goal directly (which will not generate the site first, making it
appropriate if the site has already been generated - for example after the multiproject:site
goal).
Where the site is deployed to is controlled by the pom.siteAddress and
pom.siteDirectory properties, which control the server and absolute directory
respectively.
| Method | Goal | Description |
|---|---|---|
ssh |
site:sshdeploy |
This uses SSH to transfer the files. The site is first packaged into a compressed tar archive,
transferred using scp, then uncompressed using remote commands via ssh.
This method requires that you have ssh and scp locally (PuTTY will suffice
as long as your properties are set correctly).
It also requires that your remote server has an SSH server running, with tar and
gunzip available. This also requires that you have a suitable SSH agent and private
key set up such that you can log in to the remote server without having to enter a password.
|
ftp |
site:ftpdeploy |
This uses FTP to transfer the files. The site directory is recursively copied to the remote server. Note that unused files will not be removed. This method requires that an FTP server be running on the remote server. Requires Maven 1.1 |
rsync |
site:rsyncdeploy |
This uses rsync to transfer the files. This requires that you have rsync
installed both locally and remotely, that RSYNC_RSH is set correctly, and that you can
login remotely without having to enter a password. This is usually done over SSH, as described above.
By default, this method does not remove unused files: set the maven.site.deploy.clean
property to true if this is desired.
|
fs |
site:fsdeploy |
This method copies the site to a location on the local filesystem.
By default, this method does not remove unused files: set the maven.site.deploy.clean
property to true if this is desired.
|
In some cases, you may want to publish the site in two stages. This facilitates reviewing the site before it goes live, or having a backup location of the site.
To enable this method, set the maven.site.stage.address and/or
maven.site.stage.directory properties. These are equivalent to the properties set in the
POM, but designate the location of the staging server. If one of these properties is not specified,
it will default to the same value as the POM for the staging server.
Once these properties are set, the site:deploy goal (including the individual method
deployment goals) will publish to the staging environment instead.
To publish the site live, run:
maven site:publish
Note that, unless you are publishing with both source and destination locally, this goal requires that an
SSH server is running on both the live and stage servers, and that
both have the rsync executable. You must have permission to SSH to the stage server without
entering a password using an SSH agent, and the stage server must likewise be able to SSH to the
live server if it is different. Additionally, the target directory must exist on the live server.
If this configuration can not be enabled for your environment, you should publish the site a second time from your local environment to publish it live. This can be accomplished by running:
maven site:deploy -Dmaven.site.deploy.live=true