o Fix html generation

o Categorize reports in "Project Info" and "Project Reports"
o Generate overview page for "Project Info" and "Project Reports" pages

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

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

@@ -28,6 +28,7 @@ import org.codehaus.plexus.util.FileUtils;
 import org.codehaus.plexus.util.StringInputStream;
 import org.codehaus.plexus.util.StringUtils;
 
+import java.util.ArrayList;
 import java.io.File;
 import java.io.InputStream;
 import java.io.IOException;
@@ -110,17 +111,23 @@ public class DoxiaMojo
      */
     private List remoteRepositories;
 
+    private List projectInfos = new ArrayList();
+    private List projectReports = new ArrayList();
+
     public void execute()
         throws MojoExecutionException
     {
         try
         {
+            categorizeReports();
+
             MavenReportConfiguration config = new MavenReportConfiguration();
 
             config.setModel( project.getModel() );
 
             config.setOutputDirectory( new File( generatedSiteDirectory ) );
 
+            //Generate reports
             if ( reports != null )
             {
                 for ( Iterator i = reports.keySet().iterator(); i.hasNext(); )
@@ -141,8 +148,35 @@ public class DoxiaMojo
                 }
             }
 
-            siteRenderer.render( siteDirectory, generatedSiteDirectory, outputDirectory, flavour,
+            //Generate overview pages
-                                 getSiteDescriptor() );
+            if ( projectInfos.size() > 0 )
+            {
+                try
+                {
+                    generateProjectInfoPage( getSiteDescriptor() );
+                }
+                catch ( Exception e )
+                {
+                    e.printStackTrace();
+                    throw new MojoExecutionException( "An error is occurred in project info page generation.", e );
+                }
+            }
+
+            if ( projectReports.size() > 0 )
+            {
+                try
+                {
+                    generateProjectReportsPage( getSiteDescriptor() );
+                }
+                catch ( Exception e )
+                {
+                    e.printStackTrace();
+                    throw new MojoExecutionException( "An error is occurred in project reports page generation.", e );
+                }
+            }
+
+            //Generate static site
+            siteRenderer.render( siteDirectory, generatedSiteDirectory, outputDirectory, flavour, getSiteDescriptor() );
         }
         catch ( Exception e )
         {
@@ -151,21 +185,67 @@ public class DoxiaMojo
         }
     }
 
+    private void categorizeReports()
+        throws MojoExecutionException
+    {
+        for ( Iterator i = reports.values().iterator(); i.hasNext(); )
+        {
+            MavenReport report = (MavenReport) i.next();
+            if ( MavenReport.CATEGORY_PROJECT_INFORMATION.equals( report.getCategoryName() ) )
+            {
+                projectInfos.add( report );
+            }
+            else if ( MavenReport.CATEGORY_PROJECT_REPORTS.equals( report.getCategoryName() ) )
+            {
+                projectReports.add( report );
+            }
+            else
+            {
+                throw new MojoExecutionException( "'" + report.getCategoryName() + "' category define for " +
+                                                  report.getName() + " mojo isn't valid." );
+            }
+        }
+    }
+
     private String getReportsMenu()
+        throws MojoExecutionException
     {
         StringBuffer buffer = new StringBuffer();
         buffer.append( "<menu name=\"Project Documentation\">\n" );
         buffer.append( "    <item name=\"About " + project.getName() + "\" href=\"/index.html\"/>\n");
-        buffer.append( "    <item name=\"Project reports\" href=\"/maven-reports.html\" collapse=\"true\">\n" );
 
-        for ( Iterator i = reports.keySet().iterator(); i.hasNext(); )
+        if ( projectInfos.size() > 0 )
         {
-            String reportKey = (String) i.next();
+            buffer.append( "    <item name=\"" + MavenReport.CATEGORY_PROJECT_INFORMATION +
-            buffer.append( "        <item name=\"" + reportKey + "\" href=\"/" + reportKey + ".html\"/>\n" );
+                           "\" href=\"/project-info.html\" collapse=\"true\">\n" );
+
+            for ( Iterator i = projectInfos.iterator(); i.hasNext(); )
+            {
+                MavenReport report = (MavenReport) i.next();
+                buffer.append( "        <item name=\"" + report.getName() + "\" href=\"/" +
+                               report.getOutputName() + ".html\"/>\n" );
+            }
+
+            buffer.append( "    </item>\n" );
+        }
+
+        if ( projectReports.size() > 0 )
+        {
+            buffer.append( "    <item name=\"" + MavenReport.CATEGORY_PROJECT_REPORTS +
+                           "\" href=\"/maven-reports.html\" collapse=\"true\">\n" );
+
+            for ( Iterator i = projectReports.iterator(); i.hasNext(); )
+            {
+                MavenReport report = (MavenReport) i.next();
+                buffer.append( "        <item name=\"" + report.getName() + "\" href=\"/" +
+                               report.getOutputName() + ".html\"/>\n" );
+            }
+
+            buffer.append( "    </item>\n" );
         }
 
-        buffer.append( "    </item>\n" );
         buffer.append( "</menu>\n" );
+
         return buffer.toString();
     }
 
@@ -198,7 +278,150 @@ public class DoxiaMojo
         }
 
         siteDescriptorContent = StringUtils.interpolate( siteDescriptorContent, props );
-
+        
         return new StringInputStream( siteDescriptorContent );
     }
+
+    private void generateProjectInfoPage( InputStream siteDescriptor )
+        throws Exception
+    {
+        XhtmlSink sink = siteRenderer.createSink( new File( siteDirectory ), siteDirectory,
+                                                  "project-info.html",
+                                                  outputDirectory, siteDescriptor, flavour );
+
+        String title = "General Project Information";
+
+        sink.head();
+        sink.title();
+        sink.text( title );
+        sink.title_();
+        sink.head_();
+        sink.body();
+
+        sink.section1();
+        sink.sectionTitle1();
+        sink.text( title );
+        sink.sectionTitle1_();
+
+        sink.paragraph();
+        sink.text( "This document provides an overview of the various documents and links that are part " +
+                   "of this project's general information. All of this content is automatically generated by ");
+        sink.link( "http://maven.apache.org" );
+        sink.text( "Maven" );
+        sink.link_();
+        sink.text( " on behalf of the project." );
+        sink.paragraph_();
+
+        sink.section2();
+
+        sink.sectionTitle2();
+        sink.text( "Overview" );
+        sink.sectionTitle2_();
+
+        sink.table();
+
+        sink.tableRow();
+        sink.tableHeaderCell();
+        sink.text( "Document" );
+        sink.tableHeaderCell_();
+        sink.tableHeaderCell();
+        sink.text( "Description" );
+        sink.tableHeaderCell_();
+        sink.tableRow_();
+
+        for ( Iterator i = projectInfos.iterator(); i.hasNext(); )
+        {
+            MavenReport report = (MavenReport) i.next();
+
+            sink.tableRow();
+            sink.tableCell();
+            sink.link( report.getOutputName() + ".html" );
+            sink.text( report.getName() );
+            sink.link_();
+            sink.tableCell_();
+            sink.tableCell();
+            sink.text( report.getDescription() );
+            sink.tableCell_();
+            sink.tableRow_();
+        }
+
+        sink.table_();
+        
+        sink.section2_();
+
+        sink.section1_();
+
+        sink.body_();
+    }
+
+    private void generateProjectReportsPage( InputStream siteDescriptor)
+        throws Exception
+    {
+        XhtmlSink sink = siteRenderer.createSink( new File( siteDirectory ), siteDirectory,
+                                                  "maven-reports.html",
+                                                  outputDirectory, siteDescriptor, flavour );
+
+        String title = "Maven Generated Reports";
+
+        sink.head();
+        sink.title();
+        sink.text( title );
+        sink.title_();
+        sink.head_();
+        sink.body();
+
+        sink.section1();
+        sink.sectionTitle1();
+        sink.text( title );
+        sink.sectionTitle1_();
+
+        sink.paragraph();
+        sink.text( "This document provides an overview of the various reports that are automatically generated by " );
+        sink.link( "http://maven.apache.org" );
+        sink.text( "Maven" );
+        sink.link_();
+        sink.text( ". Each report is briefly described below." );
+        sink.paragraph_();
+
+        sink.section2();
+
+        sink.sectionTitle2();
+        sink.text( "Overview" );
+        sink.sectionTitle2_();
+
+        sink.table();
+
+        sink.tableRow();
+        sink.tableHeaderCell();
+        sink.text( "Document" );
+        sink.tableHeaderCell_();
+        sink.tableHeaderCell();
+        sink.text( "Description" );
+        sink.tableHeaderCell_();
+        sink.tableRow_();
+
+        for ( Iterator i = projectReports.iterator(); i.hasNext(); )
+        {
+            MavenReport report = (MavenReport) i.next();
+
+            sink.tableRow();
+            sink.tableCell();
+            sink.link( report.getOutputName() + ".html" );
+            sink.text( report.getName() );
+            sink.link_();
+            sink.tableCell_();
+            sink.tableCell();
+            sink.text( report.getDescription() );
+            sink.tableCell_();
+            sink.tableRow_();
+        }
+
+        sink.table_();
+        
+        sink.section2_();
+
+        sink.section1_();
+
+        sink.body_();
+    }
 }

maven-reporting/maven-reporting-api/src/main/java/org/apache/maven/reporting/AbstractMavenReport.java

@@ -74,4 +74,9 @@ public abstract class AbstractMavenReport
     {
         return sink;
     }
+
+    public String getCategoryName()
+    {
+        return CATEGORY_PROJECT_REPORTS;
+    }
 }

maven-reporting/maven-reporting-api/src/main/java/org/apache/maven/reporting/AbstractMavenReportRenderer.java

@@ -73,18 +73,23 @@ public abstract class AbstractMavenReportRenderer
         {
             case 1:
                 sink.section1();
+                sink.sectionTitle1();
                 break;
             case 2:
                 sink.section2();
+                sink.sectionTitle2();
                 break;
             case 3:
                 sink.section3();
+                sink.sectionTitle3();
                 break;
             case 4:
                 sink.section4();
+                sink.sectionTitle4();
                 break;
             case 5:
                 sink.section5();
+                sink.sectionTitle5();
                 break;
 
             default:
@@ -92,11 +97,30 @@ public abstract class AbstractMavenReportRenderer
                 break;
         }
 
-        sink.sectionTitle();
-
         sink.text( name );
 
-        sink.sectionTitle_();
+        switch ( section )
+        {
+            case 1:
+                sink.sectionTitle1_();
+                break;
+            case 2:
+                sink.sectionTitle2_();
+                break;
+            case 3:
+                sink.sectionTitle3_();
+                break;
+            case 4:
+                sink.sectionTitle4_();
+                break;
+            case 5:
+                sink.sectionTitle5_();
+                break;
+
+            default:
+                // TODO: warning - just don't start a section
+                break;
+        }
     }
 
     protected void endSection()

maven-reporting/maven-reporting-api/src/main/java/org/apache/maven/reporting/MavenReport.java

@@ -32,6 +32,10 @@ public interface MavenReport
 {
     String ROLE = MavenReport.class.getName();
 
+    String CATEGORY_PROJECT_INFORMATION = "Project Info";
+
+    String CATEGORY_PROJECT_REPORTS = "Project Reports";
+
     MavenReportConfiguration getConfiguration();
 
     void setConfiguration( MavenReportConfiguration config );
@@ -41,6 +45,12 @@ public interface MavenReport
 
     String getOutputName();
 
+    String getName();
+
+    String getCategoryName();
+
+    String getDescription();
+
     Sink getSink()
         throws IOException;
 }

sandbox/maven-reports/maven-checkstyle-plugin/src/main/java/org/apache/maven/plugin/checkstyle/CheckstyleReport.java

@@ -76,6 +76,16 @@ public class CheckstyleReport
 
     private boolean failedOnError = false;
 
+    public String getName()
+    {
+        return "Checkstyle";
+    }
+
+    public String getDescription()
+    {
+        return "Report on coding style conventions.";
+    }
+
     public void execute()
         throws MavenReportException
     {
@@ -91,6 +101,8 @@ public class CheckstyleReport
             File resultFile = new File( getConfiguration().getOutputDirectory(), resultFileName );
             try
             {
+                File parentFile = resultFile.getParentFile();
+                parentFile.mkdirs();
                 out = new FileOutputStream( resultFile );
             }
             catch( IOException e )

sandbox/maven-reports/maven-checkstyle-plugin/src/main/java/org/apache/maven/plugin/checkstyle/CheckstyleReportListener.java

@@ -59,9 +59,9 @@ public class CheckstyleReportListener
         sink.body();
 
         sink.section1();
-        sink.sectionTitle();
+        sink.sectionTitle1();
         sink.text( TITLE );
-        sink.sectionTitle_();
+        sink.sectionTitle1_();
 
         sink.paragraph();
         sink.text( "The following document contains the results of " );
@@ -73,9 +73,9 @@ public class CheckstyleReportListener
         // TODO overall summary
 
         sink.section1_();
-        sink.sectionTitle();
+        sink.sectionTitle1();
         sink.text( "Files" );
-        sink.sectionTitle_();
+        sink.sectionTitle1_();
 
         // TODO files summary
     }
@@ -109,9 +109,9 @@ public class CheckstyleReportListener
             if ( !fileInitialized )
             {
                 sink.section2();
-                sink.sectionTitle();
+                sink.sectionTitle2();
                 sink.text( currentFilename );
-                sink.sectionTitle_();
+                sink.sectionTitle2_();
 
                 sink.table();
                 sink.tableRow();

sandbox/maven-reports/maven-pmd-plugin/src/main/java/org/apache/maven/plugin/pmd/PmdReport.java

@@ -63,6 +63,16 @@ public class PmdReport
         // Mac
         "**/.DS_Store"};
 
+    public String getName()
+    {
+        return "PMD report";
+    }
+
+    public String getDescription()
+    {
+        return "Verification of coding rules.";
+    }
+
     public void execute()
         throws MavenReportException
     {

sandbox/maven-reports/maven-pmd-plugin/src/main/java/org/apache/maven/plugin/pmd/PmdReportListener.java

@@ -69,9 +69,9 @@ public class PmdReportListener
         sink.body();
 
         sink.section1();
-        sink.sectionTitle();
+        sink.sectionTitle1();
         sink.text( TITLE );
-        sink.sectionTitle_();
+        sink.sectionTitle1_();
 
         sink.paragraph();
         sink.text( "The following document contains the results of " );
@@ -83,9 +83,9 @@ public class PmdReportListener
         // TODO overall summary
 
         sink.section1_();
-        sink.sectionTitle();
+        sink.sectionTitle1();
         sink.text( "Files" );
-        sink.sectionTitle_();
+        sink.sectionTitle1_();
 
         // TODO files summary
     }
@@ -93,9 +93,9 @@ public class PmdReportListener
     public void beginFile( File file )
     {
         sink.section2();
-        sink.sectionTitle();
+        sink.sectionTitle2();
         sink.text( file.getPath() );
-        sink.sectionTitle_();
+        sink.sectionTitle2_();
 
         sink.table();
         sink.tableRow();

sandbox/maven-reports/maven-project-info-reports-plugin/src/main/java/org/apache/maven/report/projectinfo/DependenciesReport.java

@@ -34,6 +34,21 @@ import java.util.Iterator;
 public class DependenciesReport
     extends AbstractMavenReport
 {
+    public String getName()
+    {
+        return "Dependencies";
+    }
+
+    public String getCategoryName()
+    {
+        return CATEGORY_PROJECT_INFORMATION;
+    }
+
+    public String getDescription()
+    {
+        return "This document lists the projects dependencies and provides information on each dependency.";
+    }
+
     public void execute()
         throws MavenReportException
     {
@@ -76,20 +91,30 @@ public class DependenciesReport
         {
             startSection( getTitle() );
 
-            startTable();
+            if ( model.getDependencies().isEmpty() )
-
-            tableCaption( "Declared Dependencies" );
-
-            tableHeader( new String[]{"GroupId", "ArtifactId", "Version"} );
-
-            for ( Iterator i = model.getDependencies().iterator(); i.hasNext(); )
             {
-                Dependency d = (Dependency) i.next();
+                // TODO: should the report just be excluded?
-
+                paragraph( "There are no dependencies for this project. It is a standalone " +
-                tableRow( new String[]{d.getGroupId(), d.getArtifactId(), d.getVersion()} );
+                           "application that does not depend on any other project." );
             }
+            else
+            {
+                startTable();
 
-            endTable();
+                tableCaption( "The following is a list of dependencies for this project. These dependencies " +
+                              "are required to compile and run the application:" );
+
+                tableHeader( new String[]{"GroupId", "ArtifactId", "Version"} );
+
+                for ( Iterator i = model.getDependencies().iterator(); i.hasNext(); )
+                {
+                    Dependency d = (Dependency) i.next();
+
+                    tableRow( new String[]{d.getGroupId(), d.getArtifactId(), d.getVersion()} );
+                }
+
+                endTable();
+            }
 
             endSection();
         }

sandbox/maven-reports/maven-project-info-reports-plugin/src/main/java/org/apache/maven/report/projectinfo/MailingListsReport.java

@@ -33,6 +33,21 @@ import java.util.Iterator;
 public class MailingListsReport
     extends AbstractMavenReport
 {
+    public String getName()
+    {
+        return "Mailing Lists";
+    }
+
+    public String getCategoryName()
+    {
+        return CATEGORY_PROJECT_INFORMATION;
+    }
+
+    public String getDescription()
+    {
+        return "This document provides subscription and archive information for this project's mailing lists.";
+    }
+
     public void execute()
         throws MavenReportException
     {