PR: MNG-902

Submitted by: Allan Ramirez
Reviewed by:  Brett Porter
documentation for the site plugin

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@290648 13f79535-47bb-0310-9956-ffa450edef68

maven-plugins/maven-site-plugin/src/main/java/org/apache/maven/doxia/DoxiaMojo.java

@@ -95,6 +95,8 @@ public class DoxiaMojo
         "**/.DS_Store"};
 
     /**
+     * Directory that contains the reports in apt/fml format.
+     *
      * @parameter expression="${basedir}/src/site"
      * @required
      */
@@ -107,23 +109,31 @@ public class DoxiaMojo
     private File generatedSiteDirectory;
 
     /**
+     * Directory that contains the generated reports.
+     *
      * @parameter expression="${project.build.directory}/site"
      * @required
      */
     private File outputDirectory;
 
     /**
+     * Directory which contains the resources for the site.
+     *
      * @parameter expression="${basedir}/src/site/resources"
      * @required
      */
     private File resourcesDirectory;
 
     /**
+     * Directory containing the template page.
+     *
      * @parameter expression="${templateDirectory}"
      */
     private String templateDirectory;
 
     /**
+     * Default template page.
+     *
      * @parameter expression="${template}"
      */
     private String template = DEFAULT_TEMPLATE;
@@ -161,6 +171,8 @@ public class DoxiaMojo
     private Renderer siteRenderer;
 
     /**
+     * Internationalization.
+     *
      * @parameter expression="${component.org.codehaus.plexus.i18n.I18N}"
      * @required
      * @readonly
@@ -168,6 +180,8 @@ public class DoxiaMojo
     private I18N i18n;
 
     /**
+     * The maven project.
+     *
      * @parameter expression="${project}"
      * @required
      * @readonly
@@ -409,6 +423,12 @@ public class DoxiaMojo
         }
     }
 
+    /**
+     * Categorize reports by category name.
+     *
+     * @param reports list of reports
+     * @return the categorised reports
+     */
     private Map categorizeReports( List reports )
     {
         Map categories = new HashMap();
@@ -670,7 +690,7 @@ public class DoxiaMojo
     }
 
     /**
-     * Generated an index page.
+     * Generate an index page.
      *
      * @param siteDescriptor
      * @param locale

maven-plugins/maven-site-plugin/src/site/apt/howto.apt

@@ -0,0 +1,52 @@
+ ------
+ Maven 2 Site Plugin
+ ------
+
+Maven 2 Site Plugin
+
+ Generate the project's site and report distributions.
+
+*How to Use
+
+  Using the site plugin is very easy, just execute the site goal from your project
+
+-------------------
+  m2 site:site
+-------------------
+  
+  and it would generate its default reports.
+
+  *jdepend
+
+  *checkstyle
+  
+  *surefire-report
+  
+  *javadoc
+  
+  *jxr (cross reference)
+  
+  *taglist
+  
+  *changelog
+
+
+*How to configure the default reports version
+
+  You can configure the reports version by adding arguments in the command line.
+
+-------------------
+
+  m2 site:site -DjdependVersion=2.0-beta-1 \
+	-DcheckstyleVersion=1.0 \
+	-DsurefireVersion=2.0 \
+	-DjavadocVersion=3.0 \
+
+-------------------
+
+  Note: The command is only a single line and the version value are just examples.
+
+
+*Deploying site & Site Descriptor
+
+  For more references of deploying the site and site descriptor here's a link {{{http://maven.apache.org/maven2/site.html}http://maven.apache.org/maven2/site.html}}.

maven-plugins/maven-site-plugin/src/site/site.xml

@@ -34,6 +34,7 @@
 
     <menu name="Overview">
       <item name="i18n" href="/i18n.html"/>
+      <item name="How to use" href="howto.html"/>
     </menu>
     ${reports}
   </body>