- improve documentation
- use local file copies where possible to reduce configuration git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@124835 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
brett
@@ -27,16 +27,14 @@
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<goal name="site:generate" prereqs="site"/>
|
||||
<goal name="site:site" prereqs="site" description="Generate the web site" />
|
||||
|
||||
<goal name="site:init" prereqs="xdoc:init">
|
||||
<j:set var="docsDest" value="${maven.docs.dest}"/>
|
||||
</goal>
|
||||
|
||||
|
||||
<goal
|
||||
name="site"
|
||||
description="Generate the web site">
|
||||
|
||||
<goal name="site">
|
||||
<attainGoal name="site:run-reports"/>
|
||||
<attainGoal name="xdoc"/>
|
||||
|
||||
@@ -89,7 +87,10 @@
|
||||
<j:set var="siteDirectory" value="${pom.siteDirectory}" />
|
||||
</j:if>
|
||||
|
||||
<j:set var="siteClean" value="${maven.site.deploy.clean}" />
|
||||
|
||||
<echo>
|
||||
site clean = ${siteClean}
|
||||
siteDirectory = ${siteDirectory}
|
||||
</echo>
|
||||
</goal>
|
||||
@@ -177,9 +178,7 @@
|
||||
<!-- copy the site to the directory specified in the project.xml file -->
|
||||
|
||||
<copy todir="${siteDirectory}">
|
||||
<fileset dir="${docsDest}">
|
||||
<include name="**"/>
|
||||
</fileset>
|
||||
<fileset dir="${docsDest}" />
|
||||
</copy>
|
||||
|
||||
</goal>
|
||||
@@ -239,11 +238,27 @@
|
||||
<fail>Source and destination is identical</fail>
|
||||
</j:if>
|
||||
|
||||
<!-- TODO: support local FS copy -->
|
||||
<exec dir="." executable="${maven.ssh.executable}">
|
||||
<arg line="${siteUsername}@${siteAddress} 'mkdir -p ${destSiteDirectory}; ${maven.rsync.executable} -avz ${siteDirectory}/* ${destSiteUsername}@${destSiteAddress}:${destSiteDirectory}'" />
|
||||
</exec>
|
||||
|
||||
<j:set var="deployMethod" value="${maven.site.deploy.method}" />
|
||||
<j:choose>
|
||||
<j:when test="${deployMethod == 'fs'}">
|
||||
<echo>Executing filesystem copy on local server to publish</echo>
|
||||
<copy todir="${destSiteDirectory}">
|
||||
<fileset dir="${siteDirectory}" />
|
||||
</copy>
|
||||
</j:when>
|
||||
<j:when test="${siteAddress == destSiteAddress}">
|
||||
<echo>Executing filesystem copy on remote server to publish</echo>
|
||||
<exec dir="." executable="${maven.ssh.executable}">
|
||||
<arg line="${siteUsername}@${siteAddress} 'mkdir -p ${destSiteDirectory}; cp -r ${siteDirectory}/* ${destSiteDirectory}'" />
|
||||
</exec>
|
||||
</j:when>
|
||||
<j:otherwise>
|
||||
<echo>Executing rsync on stage server to publish to live server</echo>
|
||||
<exec dir="." executable="${maven.ssh.executable}">
|
||||
<arg line="${siteUsername}@${siteAddress} '${maven.rsync.executable} -avz ${siteDirectory}/* ${destSiteUsername}@${destSiteAddress}:${destSiteDirectory}'" />
|
||||
</exec>
|
||||
</j:otherwise>
|
||||
</j:choose>
|
||||
<!-- TODO: implement optional -delete -->
|
||||
</goal>
|
||||
|
||||
@@ -262,3 +277,4 @@
|
||||
<!-- TODO: implement optional -delete -->
|
||||
</goal>
|
||||
</project>
|
||||
|
||||
|
||||
@@ -34,3 +34,4 @@ maven.rsync.executable=rsync
|
||||
|
||||
maven.username=USERNAME_NOT_SET
|
||||
|
||||
maven.site.deploy.clean=false
|
||||
|
||||
@@ -22,14 +22,140 @@
|
||||
<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.
|
||||
project. This includes both transforming your custom xdoc documents into
|
||||
XHTML (see the <a href="/reference/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 properties are set correctly - see the <a href="faq.html">FAQ</a>).
|
||||
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.
|
||||
</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:fseploy</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>
|
||||
|
||||
|
||||
@@ -51,6 +51,16 @@
|
||||
Force the use of the live deployment parameters, even if the staging ones are specified
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>maven.site.deploy.clean</td>
|
||||
<td>Yes</td>
|
||||
<td>
|
||||
This will ensure the target in either a <code>site:deploy</code> or <code>site:publish</code> goal is
|
||||
clean by either deleting the directory first, or rsync'ing with the <code>--delete</code> option.
|
||||
This operation is not atomic, so is not recommended for the live site unless you are using the rsync
|
||||
method.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>maven.scp.executable</td>
|
||||
<td>Yes</td>
|
||||
|
||||
Reference in New Issue
Block a user