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="[EMAIL PROTECTED] 'mkdir -p ${destSiteDirectory}; ${maven.rsync.executable} -avz ${siteDirectory}/* [EMAIL PROTECTED]:${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="[EMAIL PROTECTED] '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="[EMAIL PROTECTED] '${maven.rsync.executable} -avz ${siteDirectory}/* [EMAIL PROTECTED]:${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="[EMAIL PROTECTED]">Jason van Zyl</author> + <author email="[EMAIL PROTECTED]">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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
