You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/01/10 23:44:48 UTC
svn commit: r124835 - /maven/maven-1/plugins/trunk/site/plugin.jelly /maven/maven-1/plugins/trunk/site/plugin.properties /maven/maven-1/plugins/trunk/site/xdocs/index.xml /maven/maven-1/plugins/trunk/site/xdocs/properties.xml
Author: brett
Date: Mon Jan 10 14:44:46 2005
New Revision: 124835
URL: http://svn.apache.org/viewcvs?view=rev&rev=124835
Log:
- improve documentation
- use local file copies where possible to reduce configuration
Modified:
maven/maven-1/plugins/trunk/site/plugin.jelly
maven/maven-1/plugins/trunk/site/plugin.properties
maven/maven-1/plugins/trunk/site/xdocs/index.xml
maven/maven-1/plugins/trunk/site/xdocs/properties.xml
Modified: maven/maven-1/plugins/trunk/site/plugin.jelly
Url: http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/site/plugin.jelly?view=diff&rev=124835&p1=maven/maven-1/plugins/trunk/site/plugin.jelly&r1=124834&p2=maven/maven-1/plugins/trunk/site/plugin.jelly&r2=124835
==============================================================================
--- maven/maven-1/plugins/trunk/site/plugin.jelly (original)
+++ maven/maven-1/plugins/trunk/site/plugin.jelly Mon Jan 10 14:44:46 2005
@@ -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>
+
Modified: maven/maven-1/plugins/trunk/site/plugin.properties
Url: http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/site/plugin.properties?view=diff&rev=124835&p1=maven/maven-1/plugins/trunk/site/plugin.properties&r1=124834&p2=maven/maven-1/plugins/trunk/site/plugin.properties&r2=124835
==============================================================================
--- maven/maven-1/plugins/trunk/site/plugin.properties (original)
+++ maven/maven-1/plugins/trunk/site/plugin.properties Mon Jan 10 14:44:46 2005
@@ -34,3 +34,4 @@
maven.username=USERNAME_NOT_SET
+maven.site.deploy.clean=false
Modified: maven/maven-1/plugins/trunk/site/xdocs/index.xml
Url: http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/site/xdocs/index.xml?view=diff&rev=124835&p1=maven/maven-1/plugins/trunk/site/xdocs/index.xml&r1=124834&p2=maven/maven-1/plugins/trunk/site/xdocs/index.xml&r2=124835
==============================================================================
--- maven/maven-1/plugins/trunk/site/xdocs/index.xml (original)
+++ maven/maven-1/plugins/trunk/site/xdocs/index.xml Mon Jan 10 14:44:46 2005
@@ -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>
+
Modified: maven/maven-1/plugins/trunk/site/xdocs/properties.xml
Url: http://svn.apache.org/viewcvs/maven/maven-1/plugins/trunk/site/xdocs/properties.xml?view=diff&rev=124835&p1=maven/maven-1/plugins/trunk/site/xdocs/properties.xml&r1=124834&p2=maven/maven-1/plugins/trunk/site/xdocs/properties.xml&r2=124835
==============================================================================
--- maven/maven-1/plugins/trunk/site/xdocs/properties.xml (original)
+++ maven/maven-1/plugins/trunk/site/xdocs/properties.xml Mon Jan 10 14:44:46 2005
@@ -52,6 +52,16 @@
</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>
<td>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org