stephenc
/
maven-plugin-tools
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

MPLUGIN-13: Provide Automated Documentation for a Plugin That Provides a Report 

o added a new column in plugin-info page when a mojo goal is a report
o add a notice in the generate xdoc
o added new utility class
o updated i18n

git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@630057 13f79535-47bb-0310-9956-ffa450edef68
master
Vincent Siveton 2008-02-22 00:33:54 +00:00
parent c5c42c4b6b
commit e99b28f82c
10 changed files with 226 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java
View File

@ -210,7 +210,7 @@ public class PluginReport
}
private static ResourceBundle getBundle( Locale locale )
protected static ResourceBundle getBundle( Locale locale )
{
return ResourceBundle.getBundle( "plugin-report", locale, PluginReport.class.getClassLoader() );
}
@ -255,53 +255,88 @@ public class PluginReport
{
startSection( getTitle() );
if ( pluginDescriptor.getMojos() != null && pluginDescriptor.getMojos().size() > 0 )
if ( !( pluginDescriptor.getMojos() != null && pluginDescriptor.getMojos().size() > 0 ) )
{
paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) );
paragraph( getBundle( locale ).getString( "report.plugin.nogoal" ) );
endSection();
return;
}
startTable();
paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) );
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 } );
for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
boolean hasMavenReport = false;
for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
{
MojoDescriptor mojo = (MojoDescriptor) i.next();
if ( PluginUtils.isMavenReport( mojo.getImplementation() ) )
{
MojoDescriptor mojo = (MojoDescriptor) i.next();
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( description ) )
{
description = getBundle( locale ).getString( "report.plugin.goal.nodescription" );
}
String deprecated = mojo.getDeprecated();
if ( StringUtils.isNotEmpty( deprecated ) )
{
description = "<strong>" + getBundle( locale ).getString( "report.plugin.goal.deprecated" ) + "</strong> " + description;
}
sink.tableRow();
tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) );
tableCell( description, true );
sink.tableRow_();
hasMavenReport = true;
}
}
endTable();
startTable();
String goalColumnName = getBundle( locale ).getString( "report.plugin.goals.column.goal" );
String isMavenReport = getBundle( locale ).getString( "report.plugin.goals.column.isMavenReport" );
String descriptionColumnName = getBundle( locale ).getString( "report.plugin.goals.column.description" );
if ( hasMavenReport )
{
tableHeader( new String[] { goalColumnName, isMavenReport, descriptionColumnName } );
}
else
{
paragraph( getBundle( locale ).getString( "report.plugin.nogoal" ) );
tableHeader( new String[] { goalColumnName, descriptionColumnName } );
}
for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
{
MojoDescriptor mojo = (MojoDescriptor) i.next();
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( description ) )
{
description = getBundle( locale ).getString( "report.plugin.goal.nodescription" );
}
String deprecated = mojo.getDeprecated();
if ( StringUtils.isNotEmpty( deprecated ) )
{
description = "<strong>" + getBundle( locale ).getString( "report.plugin.goal.deprecated" ) + "</strong> " + description;
}
sink.tableRow();
tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) );
if ( hasMavenReport )
{
if ( PluginUtils.isMavenReport( mojo.getImplementation() ) )
{
sink.tableCell();
iconValid( locale );
sink.tableCell_();
}
else
{
sink.tableCell();
iconError( locale );
sink.tableCell_();
}
}
tableCell( description, true );
sink.tableRow_();
}
endTable();
endSection();
startSection( getBundle( locale ).getString( "report.plugin.systemrequirements" ) );
@ -370,6 +405,7 @@ public class PluginReport
sb.append( "<project>" ).append( '\n' );
sb.append( " ..." ).append( '\n' );
sb.append( " <build>" ).append( '\n' );
sb.append( " <!-- " + getBundle( locale ).getString( "report.plugin.usage.pluginManagement" ) + " -->" ).append( '\n' );
sb.append( " <pluginManagement>" ).append( '\n' );
sb.append( " <plugin>" ).append( '\n' );
sb.append( " <groupId>" ).append( pluginDescriptor.getGroupId() ).append( "<groupId>" )
@ -381,22 +417,46 @@ public class PluginReport
sb.append( " </plugin>" ).append( '\n' );
sb.append( " ..." ).append( '\n' );
sb.append( " </pluginManagement>" ).append( '\n' );
sb.append( " <!-- " + getBundle( locale ).getString( "report.plugin.usage.plugins" ) + " -->" ).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( " <version>" ).append( pluginDescriptor.getVersion() ).append( "<version>" )
.append( '\n' );
sb.append( " </plugin>" ).append( '\n' );
sb.append( " ..." ).append( '\n' );
sb.append( " </plugins>" ).append( '\n' );
sb.append( " </build>" ).append( '\n' );
if ( hasMavenReport )
{
sb.append( " ..." ).append( '\n' );
sb.append( " <!-- " + getBundle( locale ).getString( "report.plugin.usage.reporting" ) + " -->" ).append( '\n' );
sb.append( " <reporting>" ).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( " <version>" ).append( pluginDescriptor.getVersion() ).append( "<version>" )
.append( '\n' );
sb.append( " </plugin>" ).append( '\n' );
sb.append( " ..." ).append( '\n' );
sb.append( " </plugins>" ).append( '\n' );
sb.append( " </reporting>" ).append( '\n' );
}
sb.append( " ..." ).append( '\n' );
sb.append( "</project>" ).append( '\n' );
//mvn -U
verbatimText( sb.toString() );
linkPatternedText( getBundle( locale ).getString( "report.plugin.configuration.end" ) );
sink.paragraph_();
endSection();
@ -506,5 +566,25 @@ public class PluginReport
return jdk;
}
private void iconError( Locale locale )
{
sink.figure();
sink.figureCaption();
sink.text( getBundle( locale ).getString( "report.plugin.icon.error" ) );
sink.figureCaption_();
sink.figureGraphics( "images/icon_error_sml.gif" );
sink.figure_();
}
private void iconValid( Locale locale )
{
sink.figure();
sink.figureCaption();
sink.text( getBundle( locale ).getString( "report.plugin.icon.valid" ) );
sink.figureCaption_();
sink.figureGraphics( "images/icon_success_sml.gif" );
sink.figure_();
}
}
}

8
maven-plugin-plugin/src/main/resources/plugin-report.properties
View File

@ -24,6 +24,7 @@ report.plugin.title=Plugin documentation
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.isMavenReport=Report?
report.plugin.goals.column.description=Description
report.plugin.goal.nodescription=No description.
report.plugin.goal.deprecated=Deprecated.
@ -38,3 +39,10 @@ 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:
report.plugin.usage.pluginManagement=To define the plugin version in your parent POM
report.plugin.usage.plugins=To use the plugin goals in your POM or parent POM
report.plugin.usage.reporting=To use the report goals in your POM or parent POM
report.plugin.configuration.end=For more information, see {"Guide to Configuring Plug-ins", http://maven.apache.org/guides/mini/guide-configuring-plugins.html}
report.plugin.icon.valid=Yes
report.plugin.icon.error=No

16
maven-plugin-plugin/src/main/resources/plugin-report_de.properties
View File

@ -21,15 +21,16 @@ report.plugin.name=Plugin Dokumentation
report.plugin.description=Dieser Bericht dokumentiert die Goals und Parameter des Plugins.
report.plugin.title=Plugin Dokumentation
report.plugin.goals.nogoal=Keine Goals verfügbar.
report.plugin.goals.intro=Verfügbare Goals dieses Plugins:
report.plugin.goals.nogoal=Keine Goals verf\ufffdgbar.
report.plugin.goals.intro=Verf\ufffdgbare Goals dieses Plugins:
report.plugin.goals.column.goal=Goal
report.plugin.goals.column.isMavenReport=Report?
report.plugin.goals.column.description=Beschreibung
report.plugin.goal.nodescription=Keine Beschreibung.
report.plugin.goal.deprecated=Missbilligt.
report.plugin.systemrequirements=Systemvoraussetzungen
report.plugin.systemrequirements.intro=Die folgende Tabelle listet die Mindestanforderungen zum Ausführen dieses Plugins auf:
report.plugin.systemrequirements.intro=Die folgende Tabelle listet die Mindestanforderungen zum Ausf\ufffdhren dieses Plugins auf:
report.plugin.systemrequirements.nominimum=Keine Mindestanforderung.
report.plugin.systemrequirements.maven=Maven
report.plugin.systemrequirements.jdk=JDK
@ -37,4 +38,11 @@ report.plugin.systemrequirements.memory=Arbeitsspeicher
report.plugin.systemrequirements.diskspace=Festplatte
report.plugin.usage=Gebrauch
report.plugin.usage.intro=Sie können 'mvn -up' ausführen, um die aktuellste Version dieses Plugins herunterzuladen oder die gewünschte Version in der Plugin-Konfiguration Ihres Projekts angeben:
report.plugin.usage.intro=Sie k\ufffdnnen 'mvn -up' ausf\ufffdhren, um die aktuellste Version dieses Plugins herunterzuladen oder die gew\ufffdnschte Version in der Plugin-Konfiguration Ihres Projekts angeben:
report.plugin.usage.pluginManagement=Definieren die plugin version in ihr elternteil POM
report.plugin.usage.plugins=Verwenden die plugin ziele in ihr POM oder in ihr elternteil POM
report.plugin.usage.reporting=Verwenden die reportziele in ihr POM oder in elternteil POM
report.plugin.configuration.end=Zu mehr information, sie {"Guide to Configuring Plug-ins", http://maven.apache.org/guides/mini/guide-configuring-plugins.html}
report.plugin.icon.valid=Ja
report.plugin.icon.error=Nein

8
maven-plugin-plugin/src/main/resources/plugin-report_fr.properties
View File

@ -24,6 +24,7 @@ report.plugin.title=Documentation du plugin
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.isMavenReport=Rapport?
report.plugin.goals.column.description=Description
report.plugin.goal.nodescription=Pas de description.
report.plugin.goal.deprecated=Obsol\u00e8te.
@ -38,3 +39,10 @@ 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:
report.plugin.usage.pluginManagement=Pour d\u00e9finir la version du plugin dans le POM parent
report.plugin.usage.plugins=Pour utiliser les goals du plugin dans votre POM ou POM parent
report.plugin.usage.reporting=Pour utiliser les goals de rapports dans votre POM ou POM parent
report.plugin.configuration.end=Pour plus d'informations, consultez {"Guide to Configuring Plug-ins", http://maven.apache.org/guides/mini/guide-configuring-plugins.html}
report.plugin.icon.valid=Oui
report.plugin.icon.error=Non

5
maven-plugin-tools-api/pom.xml
View File

@ -38,6 +38,11 @@
<artifactId>maven-project</artifactId>
<version>2.0.4</version>
</dependency>
<dependency>
<groupId>org.apache.maven.reporting</groupId>
<artifactId>maven-reporting-api</artifactId>
<version>2.0.4</version>
</dependency>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-descriptor</artifactId>

17
maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java
View File

@ -35,6 +35,7 @@ import java.util.regex.Pattern;
import org.apache.maven.plugin.descriptor.MojoDescriptor;
import org.apache.maven.plugin.descriptor.Parameter;
import org.apache.maven.plugin.descriptor.PluginDescriptor;
import org.apache.maven.tools.plugin.util.PluginUtils;
import org.codehaus.plexus.util.IOUtil;
import org.codehaus.plexus.util.StringInputStream;
import org.codehaus.plexus.util.StringOutputStream;
@ -141,8 +142,10 @@ public class PluginXdocGenerator
w.addAttribute( "name", mojoDescriptor.getFullGoalName() );
writeReportNotice( mojoDescriptor, w );
w.startElement( "p" );
w.writeMarkup( "<strong>"+ getBundle( locale ).getString( "pluginxdoc.fullname" ) + "</strong>:" );
w.writeMarkup( "<strong>"+ getBundle( locale ).getString( "pluginxdoc.mojodescriptor.fullname" ) + "</strong>:" );
w.endElement(); //p
w.startElement( "p" );
w.writeMarkup( mojoDescriptor.getPluginDescriptor().getGroupId() + ":"
@ -177,6 +180,18 @@ public class PluginXdocGenerator
w.endElement(); // document
}
private void writeReportNotice( MojoDescriptor mojoDescriptor, XMLWriter w )
{
if ( PluginUtils.isMavenReport( mojoDescriptor.getImplementation() ) )
{
w.startElement( "p" );
w.writeMarkup( "<strong>" + getBundle( locale ).getString( "pluginxdoc.mojodescriptor.notice.note" )
+ "</strong>: " );
w.writeText( getBundle( locale ).getString( "pluginxdoc.mojodescriptor.notice.isMavenReport" ) );
w.endElement(); //p
}
}
private void writeGoalAttributes( MojoDescriptor mojoDescriptor, XMLWriter w )
{
w.startElement( "p" );

40
maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java
View File

@ -25,6 +25,7 @@ import java.util.List;
import org.apache.maven.model.Dependency;
import org.apache.maven.plugin.descriptor.PluginDescriptor;
import org.apache.maven.reporting.MavenReport;
import org.codehaus.plexus.component.repository.ComponentDependency;
import org.codehaus.plexus.util.DirectoryScanner;
import org.codehaus.plexus.util.FileUtils;
@ -150,4 +151,43 @@ public final class PluginUtils
w.endElement();
}
/**
* @param impl a Mojo implementation
* @return <code>true</code> is the Mojo implementation implements <code>MavenReport</code>,
* <code>false</code> otherwise.
*/
public static boolean isMavenReport( String impl )
{
if ( impl == null )
{
throw new IllegalArgumentException( "mojo implementation should be declared" );
}
Object mojo = null;
try
{
Class clazz = Class.forName( impl );
mojo = clazz.newInstance();
}
catch ( ClassNotFoundException e )
{
return false;
}
catch ( InstantiationException e )
{
return false;
}
catch ( IllegalAccessException e )
{
return false;
}
if ( ( mojo != null ) && ( mojo instanceof MavenReport ) )
{
return true;
}
return false;
}
}

4
maven-plugin-tools-api/src/main/resources/pluginxdoc.properties
View File

@ -20,7 +20,9 @@ pluginxdoc.no=No
pluginxdoc.description=Description
pluginxdoc.nodescription=None.
pluginxdoc.fullname=Full name
pluginxdoc.mojodescriptor.notice.note=Note
pluginxdoc.mojodescriptor.notice.isMavenReport=This Mojo should be used has a Maven report.
pluginxdoc.mojodescriptor.fullname=Full name
pluginxdoc.mojodescriptor.attributes=Attributes
pluginxdoc.mojodescriptor.deprecated=This plugin goal has been deprecated
pluginxdoc.mojodescriptor.projectRequired=Requires a Maven 2.0 project to be executed.

26
maven-plugin-tools-api/src/main/resources/pluginxdoc_de.properties
View File

@ -20,22 +20,24 @@ pluginxdoc.no=Nein
pluginxdoc.description=Beschreibung
pluginxdoc.nodescription=Keine.
pluginxdoc.fullname=Vollständiger Name
pluginxdoc.mojodescriptor.notice.note=Anmerkung
pluginxdoc.mojodescriptor.notice.isMavenReport=Dieses Mojo sollte verwendet werden hat einen Maven Report.
pluginxdoc.mojodescriptor.fullname=Vollst\ufffdndiger Name
pluginxdoc.mojodescriptor.attributes=Attribute
pluginxdoc.mojodescriptor.deprecated=Dieses Plugin-Goal ist missbilligt
pluginxdoc.mojodescriptor.projectRequired=Erfordert ein Maven 2.0 Projet zur Ausführung.
pluginxdoc.mojodescriptor.aggregator=Wird als Aggregator ausgeführt.
pluginxdoc.mojodescriptor.directInvocationOnly=Wird nur per direktem Aufruf ausgeführt.
pluginxdoc.mojodescriptor.dependencyResolutionRequired=Erfordert Abhängigkeitsauflösung von Artefakten mit Geltungsbereich
pluginxdoc.mojodescriptor.projectRequired=Erfordert ein Maven 2.0 Projet zur Ausf\ufffdhrung.
pluginxdoc.mojodescriptor.aggregator=Wird als Aggregator ausgef\ufffdhrt.
pluginxdoc.mojodescriptor.directInvocationOnly=Wird nur per direktem Aufruf ausgef\ufffdhrt.
pluginxdoc.mojodescriptor.dependencyResolutionRequired=Erfordert Abh\ufffdngigkeitsaufl\ufffdsung von Artefakten mit Geltungsbereich
pluginxdoc.mojodescriptor.since=Seit Version
pluginxdoc.mojodescriptor.phase=Bindet automatisch an die Lebenszyklusphase
pluginxdoc.mojodescriptor.executePhase1=Bedingt die Ausführung der Lebenszyklusphase
pluginxdoc.mojodescriptor.executePhase2=vor seiner eigenen Ausführung.
pluginxdoc.mojodescriptor.executeGoal1=Bedingt die Ausführung des Plugin-Goals
pluginxdoc.mojodescriptor.executeGoal2=vor seiner eigenen Ausführung.
pluginxdoc.mojodescriptor.executeLifecycle=Wird in seinem eigenen Lebenszyklus ausgeführt
pluginxdoc.mojodescriptor.onlineRequired=Erfordert die Ausführung von Maven im Online-Modus.
pluginxdoc.mojodescriptor.inheritedByDefault=Wird bei einem Multi-Projekt-Build standardmäßig NICHT vererbt.
pluginxdoc.mojodescriptor.executePhase1=Bedingt die Ausf\ufffdhrung der Lebenszyklusphase
pluginxdoc.mojodescriptor.executePhase2=vor seiner eigenen Ausf\ufffdhrung.
pluginxdoc.mojodescriptor.executeGoal1=Bedingt die Ausf\ufffdhrung des Plugin-Goals
pluginxdoc.mojodescriptor.executeGoal2=vor seiner eigenen Ausf\ufffdhrung.
pluginxdoc.mojodescriptor.executeLifecycle=Wird in seinem eigenen Lebenszyklus ausgef\ufffdhrt
pluginxdoc.mojodescriptor.onlineRequired=Erfordert die Ausf\ufffdhrung von Maven im Online-Modus.
pluginxdoc.mojodescriptor.inheritedByDefault=Wird bei einem Multi-Projekt-Build standardm\ufffd\ufffdig NICHT vererbt.
pluginxdoc.mojodescriptor.parameter.details=Parameter-Details
pluginxdoc.mojodescriptor.parameter.deprecated=Missbilligt.
pluginxdoc.mojodescriptor.parameter.name=Name

4
maven-plugin-tools-api/src/main/resources/pluginxdoc_fr.properties
View File

@ -20,7 +20,9 @@ pluginxdoc.no=Non
pluginxdoc.description=Description
pluginxdoc.nodescription=Aucune.
pluginxdoc.fullname=Nom complet
pluginxdoc.mojodescriptor.notice.note=Note
pluginxdoc.mojodescriptor.notice.isMavenReport=Ce Mojo doit \u00eatre utilis\u00e9 comme un rapport de Maven.
pluginxdoc.mojodescriptor.fullname=Nom complet
pluginxdoc.mojodescriptor.attributes=Attributs
pluginxdoc.mojodescriptor.deprecated=Le goal de ce plugin goal est obsol\u00e8te
pluginxdoc.mojodescriptor.projectRequired=Exige un projet Maven 2.0 pour \u00eatre ex\u00e9cut\u00e9.