4a497afe65
git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@521198 13f79535-47bb-0310-9956-ffa450edef68
163 lines
7.7 KiB
XML
163 lines
7.7 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership.
|
|
* The ASF licenses this file to You under the Apache License, Version 2.0
|
|
* (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
-->
|
|
|
|
<document>
|
|
|
|
<properties>
|
|
<title>Maven Site Plug-in</title>
|
|
<author email="jason@zenplex.com">Jason van Zyl</author>
|
|
<author email="brett@apache.org">Brett Porter</author>
|
|
</properties>
|
|
|
|
<body>
|
|
<section name="Maven Site Plug-in">
|
|
<p>
|
|
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 <a href="http://maven.apache.org/maven-1.x/plugins/xdoc/">xdoc plugin</a>), and
|
|
running the designated reports for your project. The result is then
|
|
packaged or deployed in the form that you desire.
|
|
</p>
|
|
<!-- TODO: migrate to core documentation, and link from here (or vice versa) -->
|
|
<subsection name="Generating the site">
|
|
<p>
|
|
To generate the site for your project, run:
|
|
</p>
|
|
<source>maven site:site</source>
|
|
<p>
|
|
The resulting site is created in <code>target/docs</code> (or whatever the
|
|
<code>maven.docs.dest</code> property is set to).
|
|
</p>
|
|
</subsection>
|
|
<subsection name="Deploying or packaging the site">
|
|
<p>
|
|
There are several alternatives for deploying and packaging the site.
|
|
</p>
|
|
<p>
|
|
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 <code>site:war</code>
|
|
or <code>site:ear</code> respectively. The site archive will be placed in
|
|
the <code>target</code> directory.
|
|
</p>
|
|
<p>
|
|
If you would like to deploy the site to a directory either locally or on a remote
|
|
host, you can use:
|
|
</p>
|
|
<source>maven site:deploy</source>
|
|
<p>
|
|
From there, it can be served from a web server.
|
|
</p>
|
|
<p>
|
|
There are several different deployment mechanisms, which are listed in the table below.
|
|
You can use them by setting the <code>maven.site.deploy.method</code> 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 <code>multiproject:site</code>
|
|
goal).
|
|
</p>
|
|
<p>
|
|
Where the site is deployed to is controlled by the <code>pom.siteAddress</code> and
|
|
<code>pom.siteDirectory</code> properties, which control the server and absolute directory
|
|
respectively.
|
|
</p>
|
|
<table>
|
|
<tr>
|
|
<th>Method</th><th>Goal</th><th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ssh</code></td>
|
|
<td><code>site:sshdeploy</code></td>
|
|
<td>
|
|
This uses SSH to transfer the files. The site is first packaged into a compressed tar archive,
|
|
transferred using <code>scp</code>, then uncompressed using remote commands via <code>ssh</code>.
|
|
This method requires that you have <code>ssh</code> and <code>scp</code> locally (PuTTY will suffice
|
|
as long as your <a href="properties.html#Using_Putty_as_ssh_client">properties</a> are set correctly).
|
|
It also requires that your remote server has an SSH server running, with <code>tar</code> and
|
|
<code>gunzip</code> 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.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>ftp</code></td>
|
|
<td><code>site:ftpdeploy</code></td>
|
|
<td>
|
|
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. <b>Requires Maven 1.1</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>rsync</code></td>
|
|
<td><code>site:rsyncdeploy</code></td>
|
|
<td>
|
|
This uses <code>rsync</code> to transfer the files. This requires that you have <code>rsync</code>
|
|
installed both locally and remotely, that <code>RSYNC_RSH</code> 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 <code>maven.site.deploy.clean</code>
|
|
property to <code>true</code> if this is desired.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>fs</code></td>
|
|
<td><code>site:fsdeploy</code></td>
|
|
<td>
|
|
This method copies the site to a location on the local filesystem.
|
|
By default, this method does not remove unused files: set the <code>maven.site.deploy.clean</code>
|
|
property to <code>true</code> if this is desired.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</subsection>
|
|
<subsection name="Publishing the site to an intermediate stage">
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
To enable this method, set the <code>maven.site.stage.address</code> and/or
|
|
<code>maven.site.stage.directory</code> 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.
|
|
</p>
|
|
<p>
|
|
Once these properties are set, the <code>site:deploy</code> goal (including the individual method
|
|
deployment goals) will publish to the staging environment instead.
|
|
</p>
|
|
<p>
|
|
To publish the site live, run:
|
|
</p>
|
|
<source>maven site:publish</source>
|
|
<p>
|
|
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 <code>rsync</code> 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.
|
|
</p>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<source>maven site:deploy -Dmaven.site.deploy.live=true</source>
|
|
</subsection>
|
|
</section>
|
|
</body>
|
|
</document>
|
|
|