Author: vsiveton Date: Fri Feb 1 14:38:22 2008 New Revision: 617684 URL: http://svn.apache.org/viewvc?rev=617684&view=rev Log: MPLUGIN-67: Document somewhere the minimum version of maven required by the plugin MPLUGIN-11: add an introduction to plugin configuration in plugin report
o reformated report to include system requirements and usage parts o added modello to generate requirements object o updated i18n Added: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties (with props) Modified: maven/plugin-tools/trunk/maven-plugin-plugin/pom.xml maven/plugin-tools/trunk/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report.properties maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties Modified: maven/plugin-tools/trunk/maven-plugin-plugin/pom.xml URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/pom.xml?rev=617684&r1=617683&r2=617684&view=diff ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/pom.xml (original) +++ maven/plugin-tools/trunk/maven-plugin-plugin/pom.xml Fri Feb 1 14:38:22 2008 @@ -210,6 +210,25 @@ </plugin> </plugins> --> + <plugins> + <plugin> + <groupId>org.codehaus.modello</groupId> + <artifactId>modello-maven-plugin</artifactId> + <version>1.0-alpha-14</version> + <executions> + <execution> + <goals> + <goal>java</goal> + </goals> + </execution> + </executions> + <configuration> + <version>1.0.0</version> + <model>src/main/mdo/pluginRequirements.mdo</model> + </configuration> + </plugin> + + </plugins> </build> <properties> @@ -230,4 +249,8 @@ <url>http://svn.apache.org/viewcvs.cgi/maven/plugin-tools/trunk/maven-plugin-plugin/</url> </scm> + <issueManagement> + <system>jira</system> + <url>http://jira.codehaus.org/browse/MPLUGIN</url> + </issueManagement> </project> Modified: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java?rev=617684&r1=617683&r2=617684&view=diff ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java (original) +++ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java Fri Feb 1 14:38:22 2008 @@ -19,8 +19,17 @@ * under the License. */ +import java.io.File; +import java.io.IOException; +import java.util.Iterator; +import java.util.Locale; +import java.util.Map; +import java.util.ResourceBundle; + import org.apache.maven.doxia.sink.Sink; import org.apache.maven.doxia.siterenderer.Renderer; +import org.apache.maven.model.Plugin; +import org.apache.maven.model.ReportPlugin; import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException; import org.apache.maven.plugin.descriptor.MojoDescriptor; import org.apache.maven.plugin.descriptor.PluginDescriptor; @@ -29,24 +38,18 @@ import org.apache.maven.reporting.AbstractMavenReportRenderer; import org.apache.maven.reporting.MavenReportException; import org.apache.maven.tools.plugin.extractor.ExtractionException; -import org.apache.maven.tools.plugin.generator.Generator; import org.apache.maven.tools.plugin.generator.PluginXdocGenerator; import org.apache.maven.tools.plugin.scanner.MojoScanner; import org.apache.maven.tools.plugin.util.PluginUtils; import org.codehaus.plexus.util.StringUtils; - -import java.io.File; -import java.io.IOException; -import java.util.Iterator; -import java.util.Locale; -import java.util.ResourceBundle; +import org.codehaus.plexus.util.xml.Xpp3Dom; /** * Generates the Plugin's documentation report. * * @author <a href="[EMAIL PROTECTED]">Stephane Nicoll</a> * @author <a href="mailto:[EMAIL PROTECTED]">Vincent Siveton</a> - * @version $Id $ + * @version $Id$ * @goal report */ public class PluginReport @@ -83,6 +86,28 @@ */ protected MojoScanner mojoScanner; + /** + * Specify some requirements to execute this plugin. + * Example: + * <pre> + * <requirements><br/> + * <maven>2.0</maven><br/> + * <jdk>1.4</jdk><br/> + * <memory>256m</memory><br/> + * <diskSpace>1m</diskSpace><br/> + * <others><br/> + * <property><br/> + * <name>SVN</name><br/> + * <value>1.4.6</value><br/> + * </property><br/> + * </others><br/> + * </requirements> + * </pre> + * + * @parameter + */ + private Requirements requirements; + /** [EMAIL PROTECTED] */ protected Renderer getSiteRenderer() { @@ -133,7 +158,8 @@ generatePluginDocumentation( pluginDescriptor ); // Write the overview - PluginOverviewRenderer r = new PluginOverviewRenderer( getSink(), pluginDescriptor, locale ); + PluginOverviewRenderer r = new PluginOverviewRenderer( project, requirements, getSink(), pluginDescriptor, + locale ); r.render(); } catch ( InvalidPluginDescriptorException e ) @@ -174,7 +200,7 @@ File outputDir = new File( getOutputDirectory() ); outputDir.mkdirs(); - Generator generator = new PluginXdocGenerator(); + PluginXdocGenerator generator = new PluginXdocGenerator(); generator.execute( outputDir, pluginDescriptor ); } catch ( IOException e ) @@ -196,14 +222,23 @@ static class PluginOverviewRenderer extends AbstractMavenReportRenderer { + private final MavenProject project; + + private final Requirements requirements; + private final PluginDescriptor pluginDescriptor; private final Locale locale; - public PluginOverviewRenderer( Sink sink, PluginDescriptor pluginDescriptor, Locale locale ) + public PluginOverviewRenderer( MavenProject project, Requirements requirements, Sink sink, + PluginDescriptor pluginDescriptor, Locale locale ) { super( sink ); + this.project = project; + + this.requirements = ( requirements == null ? new Requirements() : requirements ); + this.pluginDescriptor = pluginDescriptor; this.locale = locale; @@ -220,41 +255,250 @@ { startSection( getTitle() ); - paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) ); + if ( pluginDescriptor.getMojos() != null && pluginDescriptor.getMojos().size() > 0 ) + { + paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) ); - startTable(); + startTable(); - String goalColumnName = getBundle( locale ).getString( "report.plugin.goals.column.goal" ); - String descriptionColumnName = getBundle( locale ).getString( "report.plugin.goals.column.description" ); + String goalColumnName = getBundle( locale ).getString( "report.plugin.goals.column.goal" ); + String descriptionColumnName = getBundle( locale ).getString( "report.plugin.goals.column.description" ); + tableHeader( new String[] { goalColumnName, descriptionColumnName } ); - tableHeader( new String[]{goalColumnName, descriptionColumnName} ); + for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); ) + { + MojoDescriptor mojo = (MojoDescriptor) i.next(); - for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); ) + String goalName = mojo.getFullGoalName(); + + /* + * Added ./ to define a relative path + * @see AbstractMavenReportRenderer#getValidHref(java.lang.String) + */ + String goalDocumentationLink = "./" + mojo.getGoal() + "-mojo.html"; + + String description = mojo.getDescription(); + if ( StringUtils.isEmpty( mojo.getDescription() ) ) + { + description = getBundle( locale ).getString( "report.plugin.goal.nodescription" ); + } + + sink.tableRow(); + tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) ); + tableCell( description, true ); + sink.tableRow_(); + } + + endTable(); + } + else { - MojoDescriptor mojo = (MojoDescriptor) i.next(); + paragraph( getBundle( locale ).getString( "report.plugin.nogoal" ) ); + } + + endSection(); + + startSection( getBundle( locale ).getString( "report.plugin.systemrequirements" ) ); + + paragraph( getBundle( locale ).getString( "report.plugin.systemrequirements.intro" ) ); + + startTable(); - String goalName = mojo.getFullGoalName(); - /* - * Added ./ to define a relative path - * @see AbstractMavenReportRenderer#getValidHref(java.lang.String) - */ - String goalDocumentationLink = "./" + mojo.getGoal() + "-mojo.html"; - String description = mojo.getDescription(); - if ( StringUtils.isEmpty( mojo.getDescription() ) ) + String maven = discoverMavenRequirement( project, requirements ); + sink.tableRow(); + tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.maven" ) ); + tableCell( ( maven != null ? maven : getBundle( locale ) + .getString( "report.plugin.systemrequirements.nominimum" ) ) ); + sink.tableRow_(); + + String jdk = discoverJdkRequirement( project, requirements ); + sink.tableRow(); + tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.jdk" ) ); + tableCell( ( jdk != null ? jdk : getBundle( locale ) + .getString( "report.plugin.systemrequirements.nominimum" ) ) ); + sink.tableRow_(); + + sink.tableRow(); + tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.memory" ) ); + tableCell( ( StringUtils.isNotEmpty( requirements.getMemory() ) + ? requirements.getMemory() + : getBundle( locale ) + .getString( + "report.plugin.systemrequirements.nominimum" ) ) ); + sink.tableRow_(); + + sink.tableRow(); + tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.diskspace" ) ); + tableCell( ( StringUtils.isNotEmpty( requirements.getDiskSpace() ) + ? requirements.getDiskSpace() + : getBundle( locale ) + .getString( + "report.plugin.systemrequirements.nominimum" ) ) ); + sink.tableRow_(); + + if ( requirements.getOthers() != null && requirements.getOthers().size() > 0 ) + { + for ( Iterator it = requirements.getOthers().keySet().iterator(); it.hasNext(); ) { - description = getBundle( locale ).getString( "report.plugin.goal.nodescription" ); + String key = it.next().toString(); + sink.tableRow(); + tableCell( key ); + tableCell( ( StringUtils.isNotEmpty( requirements.getOthers().getProperty( key ) ) ? requirements + .getOthers().getProperty( key ) : getBundle( locale ) + .getString( "report.plugin.systemrequirements.nominimum" ) ) ); + sink.tableRow_(); } - - sink.tableRow(); - tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) ); - tableCell( description, true ); - sink.tableRow_(); } - endTable(); endSection(); + + startSection( getBundle( locale ).getString( "report.plugin.usage" ) ); + + // Configuration + sink.paragraph(); + text( getBundle( locale ).getString( "report.plugin.usage.intro" ) ); + + StringBuffer sb = new StringBuffer(); + sb.append( "<project>" ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " <build>" ).append( '\n' ); + sb.append( " <pluginManagement>" ).append( '\n' ); + sb.append( " <plugin>" ).append( '\n' ); + sb.append( " <groupId>" ).append( pluginDescriptor.getGroupId() ).append( "<groupId>" ) + .append( '\n' ); + sb.append( " <artifactId>" ).append( pluginDescriptor.getArtifactId() ).append( "<artifactId>" ) + .append( '\n' ); + sb.append( " <version>" ).append( pluginDescriptor.getVersion() ).append( "<version>" ) + .append( '\n' ); + sb.append( " </plugin>" ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " </pluginManagement>" ).append( '\n' ); + sb.append( " <plugins>" ).append( '\n' ); + sb.append( " <plugin>" ).append( '\n' ); + sb.append( " <groupId>" ).append( pluginDescriptor.getGroupId() ).append( "<groupId>" ) + .append( '\n' ); + sb.append( " <artifactId>" ).append( pluginDescriptor.getArtifactId() ).append( "<artifactId>" ) + .append( '\n' ); + sb.append( " </plugin>" ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " </plugins>" ).append( '\n' ); + sb.append( " </build>" ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( "</project>" ).append( '\n' ); + + //mvn -U + verbatimText( sb.toString() ); + + sink.paragraph_(); + + endSection(); + } + + /** + * Try to lookup on the Maven prerequisites property. + * If not specified, uses the value defined by the user. + * + * @param project + * @param requirements + * @return the Maven version + */ + private static String discoverMavenRequirement( MavenProject project, Requirements requirements ) + { + String maven = requirements.getMaven(); + if ( maven == null ) + { + maven = ( project.getPrerequisites() != null ? project.getPrerequisites().getMaven() : null ); + } + + return maven; + } + + /** + * Try to lookup on the <code>org.apache.maven.plugins:maven-compiler-plugin</code> plugin to + * find the value of the <code>target</code> option. + * If not specified, uses the value defined by the user. + * If not specified, uses the value of the system property <code>java.specification.version</code>. + * + * @param project + * @param requirements + * @return the JDK version + */ + private static String discoverJdkRequirement( MavenProject project, Requirements requirements ) + { + String jdk = requirements.getJdk(); + if ( jdk == null ) + { + if ( project.getPluginManagement() != null ) + { + jdk = discoverJdkRequirementFromPlugins( project.getPluginManagement().getPluginsAsMap() ); + } + } + if ( jdk == null ) + { + jdk = discoverJdkRequirementFromPlugins( project.getPluginArtifactMap() ); + } + if ( jdk == null ) + { + jdk = System.getProperty( "java.specification.version" ); + } + + return jdk; + } + + /** + * @param pluginsAsMap + * @return the value of the <code>target</code> in the configuration of <code>maven-compiler-plugin</code>. + */ + private static String discoverJdkRequirementFromPlugins( Map pluginsAsMap ) + { + if ( pluginsAsMap == null ) + { + return null; + } + + String jdk = null; + for ( Iterator it = pluginsAsMap.keySet().iterator(); it.hasNext(); ) + { + String key = it.next().toString(); + + if ( !key.equals( "org.apache.maven.plugins:maven-compiler-plugin" ) ) + { + continue; + } + + Object value = pluginsAsMap.get( key ); + Xpp3Dom pluginConf = null; + + if ( value instanceof Plugin ) + { + Plugin plugin = (Plugin) value; + + pluginConf = (Xpp3Dom) plugin.getConfiguration(); + } + + if ( value instanceof ReportPlugin ) + { + ReportPlugin reportPlugin = (ReportPlugin) value; + + pluginConf = (Xpp3Dom) reportPlugin.getConfiguration(); + } + + if ( pluginConf == null ) + { + continue; + } + + if ( pluginConf.getChild( "target" ) != null ) + { + continue; + } + + jdk = pluginConf.getChild( "target" ).getValue(); + } + + return jdk; } } } Added: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo?rev=617684&view=auto ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo (added) +++ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo Fri Feb 1 14:38:22 2008 @@ -0,0 +1,78 @@ +<?xml version="1.0"?> + +<!-- +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. +--> + +<model> + <id>pluginRequirements</id> + <name>PluginRequirements</name> + <description><![CDATA[Model to specify plugin requirements.]]></description> + <defaults> + <default> + <key>package</key> + <value>org.apache.maven.plugin.plugin</value> + </default> + </defaults> + <classes> + <class> + <name>Requirements</name> + <description>Plugin requirements.</description> + <version>1.0.0</version> + <fields> + <field> + <name>maven</name> + <description>The minimum version of Maven to run this plugin.</description> + <version>1.0.0</version> + <type>String</type> + <identifier>true</identifier> + <defaultValue>2.0</defaultValue> + </field> + <field> + <name>jdk</name> + <description>The minimum version of the JDK to run this plugin.</description> + <version>1.0.0</version> + <type>String</type> + <identifier>true</identifier> + </field> + <field> + <name>memory</name> + <description>The minimum memory needed to run this plugin.</description> + <version>1.0.0</version> + <type>String</type> + </field> + <field> + <name>diskSpace</name> + <description>The minimum diskSpace needed to run this plugin.</description> + <version>1.0.0</version> + <type>String</type> + </field> + <field> + <name>others</name> + <description>Others requirements properties.</description> + <version>1.0.0</version> + <type>Properties</type> + <association xml.mapStyle="inline"> + <type>String</type> + <multiplicity>*</multiplicity> + </association> + </field> + </fields> + </class> + </classes> +</model> Modified: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report.properties URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report.properties?rev=617684&r1=617683&r2=617684&view=diff ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report.properties (original) +++ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report.properties Fri Feb 1 14:38:22 2008 @@ -21,7 +21,19 @@ report.plugin.description=This report provides goals and parameters documentation of a plugin report.plugin.title=Plugin documentation -report.plugin.goals.intro=Goals available: +report.plugin.goals.nogoal=No goals available yet. +report.plugin.goals.intro=Goals available for this plugin: report.plugin.goals.column.goal=Goal report.plugin.goals.column.description=Description -report.plugin.goal.nodescription=No description \ No newline at end of file +report.plugin.goal.nodescription=No description. + +report.plugin.systemrequirements=System Requirements +report.plugin.systemrequirements.intro=The following specifies the minimum requirements to run this Maven plugin: +report.plugin.systemrequirements.nominimum= No minimum requirement. +report.plugin.systemrequirements.maven=Maven +report.plugin.systemrequirements.jdk=JDK +report.plugin.systemrequirements.memory=Memory +report.plugin.systemrequirements.diskspace=Disk Space + +report.plugin.usage=Usage +report.plugin.usage.intro=You could run 'mvn -up' to get the latest version of this plugin, or specify the version in your project's plugin configuration: Added: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties?rev=617684&view=auto ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties (added) +++ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties Fri Feb 1 14:38:22 2008 @@ -0,0 +1,23 @@ +# 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: +# This bundle is intentionally empty because English strings are provided by the base bundle via the parent chain. It +# must be provided nevertheless such that a request for locale "en" will not errorneously pick up the bundle for the +# JVM's default locale (which need not be "en"). See the method javadoc about +# ResourceBundle.getBundle(String, Locale, ClassLoader) +# for a full description of the lookup strategy. Propchange: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties ------------------------------------------------------------------------------ svn:eol-style = native Propchange: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_en.properties ------------------------------------------------------------------------------ svn:keywords = "Author Date Id Revision" Modified: maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties URL: http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties?rev=617684&r1=617683&r2=617684&view=diff ============================================================================== --- maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties (original) +++ maven/plugin-tools/trunk/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties Fri Feb 1 14:38:22 2008 @@ -18,10 +18,22 @@ # report.plugin.name=Documentation du plugin -report.plugin.description=Ce rapport fournit de la documenations sur les goals et les paramètres d'un plugin +report.plugin.description=Ce rapport fournit de la documentation sur les goals et les param\u00eatres d'un plugin report.plugin.title=Documentation du plugin -report.plugin.goals.intro=Goals disponibles : +report.plugin.goals.nogoal=Aucun goal disponible. +report.plugin.goals.intro=Goals disponibles pour ce plugin: report.plugin.goals.column.goal=Goal report.plugin.goals.column.description=Description -report.plugin.goal.nodescription=Pas de description \ No newline at end of file +report.plugin.goal.nodescription=Pas de description. + +report.plugin.systemrequirements=Exigences Syst\u00e8mes +report.plugin.systemrequirements.intro=Ce qui suit sp\u00e9cifie les exigences minimales pour \u00e9x\u00e9cuter ce plugin Maven: +report.plugin.systemrequirements.nominimum= Aucune \u00e9xigence minimale. +report.plugin.systemrequirements.maven=Maven +report.plugin.systemrequirements.jdk=JDK +report.plugin.systemrequirements.memory=M\u00e9moire +report.plugin.systemrequirements.diskspace=Espace Disque + +report.plugin.usage=Utilisation +report.plugin.usage.intro=Vous pouvez appeler 'mvn -up' pour obtenir la derni\u00e8re version de ce plugin, ou sp\u00e9cifier la version dans la configuration de votre projet: