------
 Usage
 ------
 Vincent Siveton
 <vincent.siveton@gmail.com>
 Maria Odea Ching
 ------
 17 July 2006
 ------

 ~~ 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.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html


Usage

 You can put additional content (e.g. documentation, resources, etc.) in your
 site. See {{{examples/creating-content.html}Creating Content}} for more
 information on this. If you want to change the menus, breadcrumbs, links or
 logos on your pages you need to add and configure a
 {{{examples/sitedescriptor.html}site descriptor}}. If you like, you also can
 let Maven generate some {{{examples/configuring-reports.html}reports}} for you,
 based on the contents of your POM.

* Generating a Site

  To generate the project's site and reports, execute:

+-----+
mvn site
+-----+

  By default, the resulting site will be in the <<<target/site/>>> directory.

* Deploying a Site

  To be able to deploy the site, you must first specify where the site will be
  deployed. This is set in the <<<\<distributionManagement\>>>> element of the
  POM as shown below.

+-----+
<project>
  ...
  <distributionManagement>
    <site>
      <id>www.yourcompany.com</id>
      <url>scp://www.yourcompany.com/www/docs/project/</url>
    </site>
  </distributionManagement>
  ...
</project>
+-----+

  The <<<\<id\>>>> element identifies the repository, so that you can attach
  credentials to it in your <<<settings.xml>>> file using the
  {{{http://maven.apache.org/settings.html#Servers}<<<\<servers\>>>> element}}
  as you would for any other repository.

  The <<<\<url\>>>> gives the location to deploy to. Currently, the <<<scp>>>
  and <<<file>>> protocols are supported. In the example above we copy to the
  host <<<www.mycompany.com>>> in the path <<</www/docs/project/>>>. If
  subprojects inherit the site URL from a parent POM, they will automatically
  append their <<<\<artifactId\>>>> to form their effective deployment location.

  Now you can execute the <<<{{{deploy-mojo.html}site:deploy}}>>> goal from
  your project.

  <<Note:>> A site must be generated first before executing <<<site:deploy>>>.

+-----+
mvn site:deploy
+-----+

  If you want to generate the site <and> deploy it in one go, you can utilize
  the <<<site-deploy>>> phase of the site lifecycle. To do this, just execute:

+-----+
mvn site-deploy
+-----+

* Staging a Site

  <<Note:>> This goal is available in version 2.0-beta-5 or later of the Site Plugin.

  To review/test the generated web site before an official deploy, you can stage the site in
  a specific directory. It will use the <<<\<distributionManagement\>>>> element or the project hierarchy to link the
  project and its modules.

  Just execute the <<<{{{stage-mojo.html}site:stage}}>>> goal from your project
  with the <<<stagingDirectory>>> parameter as shown below:

+-----+
mvn site:stage -DstagingDirectory=C:\fullsite
+-----+

  <<Note:>> <<<stagingDirectory>>> cannot be dynamic, i.e. <<<stagingDirectory=$\{basedir\}\fullsite>>>

  To stage a site and to deploy it, just execute the <<<{{{stage-deploy-mojo.html}site:stage-deploy}}>>> goal from your project
  with the required parameters. The <<<site:stage-deploy>>> goal will use the
  id <<<stagingSite>>> for deployment. So if you need to add your username or
  password in <<<settings.xml>>>, you should use <<<\<id\>stagingSite\</id\>>>>
  for that <<<\<server\>>>> section. See the
  {{{http://maven.apache.org/guides/mini/guide-deployment-security-settings.html}Guide to Deployment and Security Settings}}
  for more information on this.

+-----+
mvn site:stage-deploy -DstagingDirectory=C:\fullsite \
  -DstagingSiteURL=scp://www.mycompany.com/www/project/
+-----+

* Running a Site

  The Site Plugin can also be used to start up the site in Jetty. To do this,
  execute:

+-----+
mvn site:run
+-----+

  The server will, by default, be started on <<<http://localhost:8080/>>>. See
  {{{http://jetty.mortbay.org/}http://jetty.mortbay.org/}} for more information about
  the Jetty server.