dion 2004/07/18 07:20:03
Modified: plugin/src/plugin-test maven.xml plugin.jelly
plugin/xdocs navigation.xml
plugin project.xml plugin.jelly
Added: plugin/xdocs tags.xml
plugin/src/main/org/apache/maven/plugin PluginToTags.java
plugin/src/test plugin.jelly
plugin/src/test/org/apache/maven/plugin
PluginToTagsTest.java
Log:
Add the ability to generate a skeletal doc on the taglib(s) provided by plugins
Revision Changes Path
1.4 +1 -1 maven-plugins/plugin/src/plugin-test/maven.xml
Index: maven.xml
===================================================================
RCS file: /home/cvs/maven-plugins/plugin/src/plugin-test/maven.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- maven.xml 6 Jul 2004 22:22:36 -0000 1.3
+++ maven.xml 18 Jul 2004 14:20:03 -0000 1.4
@@ -28,7 +28,7 @@
<assert:assertFileExists file="${maven.docs.src}"/>
- <u:tokenize var="fileList" delim=",">navigation.xml,goals.xml</u:tokenize>
+ <u:tokenize var="fileList"
delim=",">navigation.xml,goals.xml,properties.xml,tags.xml</u:tokenize>
<j:forEach var="file" items="${fileList}">
<assert:assertFileExists file="${maven.docs.src}/${file}"/>
1.4 +1 -0 maven-plugins/plugin/src/plugin-test/plugin.jelly
Index: plugin.jelly
===================================================================
RCS file: /home/cvs/maven-plugins/plugin/src/plugin-test/plugin.jelly,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- plugin.jelly 1 May 2004 17:15:33 -0000 1.3
+++ plugin.jelly 18 Jul 2004 14:20:03 -0000 1.4
@@ -20,6 +20,7 @@
<project>
+
<goal name="goal1"
description="Build a plugin jar and install to the maven.repo.local">
1.5 +1 -0 maven-plugins/plugin/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/maven-plugins/plugin/xdocs/navigation.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- navigation.xml 1 May 2004 17:15:06 -0000 1.4
+++ navigation.xml 18 Jul 2004 14:20:03 -0000 1.5
@@ -27,6 +27,7 @@
<menu name="Overview">
<item href="/goals.html" name="Goals"/>
<item href="/properties.html" name="Properties"/>
+ <item href="/tags.html" name="Tags"/>
</menu>
</body>
</project>
1.1 maven-plugins/plugin/xdocs/tags.xml
Index: tags.xml
===================================================================
<document>
<properties>
<title>Plugin tags</title>
<author email="[EMAIL PROTECTED]">dIon Gillard</author>
</properties>
<body>
<section name='Overview'>
<p>The following tag libraries and tags are provided by this plugin.</p>
<ol>
<li><a href='#plugin_Tag_Library'>plugin</a>
<ol>
<li><a href='#uninstall_Tag'>uninstall</a></li>
<li><a href='#clearCache_Tag'>clearCache</a></li>
</ol>
</li>
<li><a href='#assert_Tag_Library'>assert</a>
<ol>
<li><a href='#assertFileExists_Tag'>assertFileExists</a></li>
<li><a href='#assertFileNotFound_Tag'>assertFileNotFound</a></li>
<li><a href='#assertEquals_Tag'>assertEquals</a></li>
</ol>
</li>
</ol>
</section>
<section name='plugin Tag Library'>
<subsection name='uninstall Tag'>
<p>
A tag to uninstall a given plugin from the various plugin directories,
including
<ol>
<li><code>${maven.plugin.dir}</code></li>
<li><code>${maven.plugin.user.dir}</code></li>
<li><code>${maven.plugin.unpacked.dir}</code></li>
</ol>
</p>
<table>
<tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
<tr>
<td>name</td>
<td>No</td>
<td>Usually this is <code>${pom.artifactId}</code></td>
</tr>
</table>
</subsection>
<subsection name='clearCache Tag'>
<p>
Clears the files used for caching plugin goals, dependencies and
tag libraries from <code>${maven.plugin.unpacked.dir}</code>
</p>
<p>There are no attributes for this tag</p>
</subsection>
</section>
<section name='assert Tag Library'>
<p>
This tag library is typically used in testing plugins. And are
similar in usage to the assert methods in a JUnit test case.
</p>
<subsection name='assertFileExists Tag'>
<p>Fails the build if the given file does not exist, otherwise no effect.</p>
<table>
<tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
<tr>
<td>file</td>
<td>No</td>
<td>The path of the file to be checked</td>
</tr>
<tr>
<td>msg</td>
<td>Yes</td>
<td>A message to be displayed when the file doesn't exist</td>
</tr>
</table>
</subsection>
<subsection name='assertFileNotFound Tag'>
<p>Fails the build if the given file does exist, otherwise no effect.</p>
<table>
<tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
<tr>
<td>file</td>
<td>No</td>
<td>The path of the file to be checked</td>
</tr>
<tr>
<td>msg</td>
<td>Yes</td>
<td>A message to be displayed when the file doesn't exist</td>
</tr>
</table>
</subsection>
<subsection name='assertEquals Tag'>
<p>Fails the build if the two values are not equal, otherwise no effect.</p>
<table>
<tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>
<tr>
<td>expected</td>
<td>No</td>
<td>The expected value</td>
</tr>
<tr>
<td>value</td>
<td>No</td>
<td>The actual value</td>
</tr>
<tr>
<td>msg</td>
<td>Yes</td>
<td>A message to be displayed when the values aren't equal.</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
1.1
maven-plugins/plugin/src/main/org/apache/maven/plugin/PluginToTags.java
Index: PluginToTags.java
===================================================================
package org.apache.maven.plugin;
/*
* ====================================================================
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed 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.
* ====================================================================
*/
import org.apache.commons.lang.StringUtils;
import org.jdom.Document;
import org.jdom.Element;
import org.jdom.JDOMException;
import org.jdom.input.SAXBuilder;
import org.jdom.xpath.XPath;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.util.HashMap;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
public class PluginToTags
{
/** plugin script */
private String pluginScript;
/** output file */
private String xdoc;
/**
* @return Returns the outputFile.
*/
public String getXdoc()
{
return xdoc;
}
/**
* @param outputFile
* The outputFile to set.
*/
public void setXdoc(String outputFile)
{
this.xdoc = outputFile;
}
/**
* @return Returns the pluginScript.
*/
public String getPluginScript()
{
return pluginScript;
}
/**
* @param pluginScript
* The plugin script to generate the docs from.
*/
public void setPluginScript(String pluginScript)
{
this.pluginScript = pluginScript;
}
/**
* Transform the plugin script to the output file. The output file will be
* in xdoc format.
*
* @throws IOException reading files
* @throws JDOMException on xml
*/
public void transform() throws JDOMException, IOException
{
File output = new File(getXdoc());
BufferedWriter bw = new BufferedWriter(new FileWriter((output)));
bw.write("<document>\n");
bw.write(" <properties>\n");
bw.write(" <title>Plugin tags</title>\n");
bw.write(" </properties>\n");
bw.write(" <body>\n");
List taglibs = getTaglibs();
writeOverview(bw, taglibs);
writeTaglibs(bw, taglibs);
bw.write(" </body>\n");
bw.write("</document>\n");
bw.close();
}
/**
* Write xdoc sections to the given writer for each taglib
* @param bw the writer
* @param taglibs a list of taglibs to output
* @throws IOException when there are errors writing
*/
private void writeTaglibs(BufferedWriter bw, List taglibs) throws IOException
{
for (Iterator taglibIter = taglibs.iterator(); taglibIter.hasNext();)
{
Map taglib = (Map) taglibIter.next();
bw.write(" <section name='" + taglib.get("uri") + " Tag Library'>\n");
List tagNames = (List)taglib.get("tagNames");
// write out subsection with name, description, attr, desc etc....
for (Iterator tagIter = tagNames.iterator(); tagIter.hasNext();)
{
String name = (String) tagIter.next();
bw.write(" <subsection name='" + name + " Tag'>\n");
bw.write(" <p>No description</p>\n");
bw.write(" <table>\n");
bw.write("
<tr><th>Attribute</th><th>Optional?</th><th>Description</th></tr>\n");
bw.write(" </table>\n");
bw.write(" </subsection>\n");
}
bw.write(" </section>\n");
}
}
/**
* Write an xdoc overview section for all taglibs
* @param bw the writer for output
* @param taglibs the taglibs to output
* @throws IOException when writing fails
*/
private void writeOverview(BufferedWriter bw, List taglibs) throws IOException
{
bw.write(" <section name='Overview'>\n");
bw.write(" <p>The following tag libraries and tags are provided by this
plugin.</p>\n");
bw.write(" <ol>\n");
for (Iterator taglibIter = taglibs.iterator(); taglibIter.hasNext();)
{
Map taglib = (Map) taglibIter.next();
String title = taglib.get("uri") + " Tag Library";
String linkStart = "<a href='#" + StringUtils.replace(title, " ", "_")
+ "'>";
bw.write(" <li>" + linkStart + taglib.get("uri") + "</a>\n");
bw.write(" <ol>\n");
List tagNames = (List)taglib.get("tagNames");
for (Iterator tagIter = tagNames.iterator(); tagIter.hasNext();)
{
String name = (String) tagIter.next();
bw.write(" <li><a href='#" + name + "_Tag'>" + name +
"</a></li>\n");
}
bw.write(" </ol>\n");
bw.write(" </li>\n");
}
bw.write(" </ol>\n");
bw.write(" </section>\n");
}
/**
* @return a list of tag libraries. Each element in the list
* is a [EMAIL PROTECTED] Map}. Each map contains an entry for "uri" (as a
String)
* and one for tagNames (as a List).
*
* @throws IOException reading files
* @throws JDOMException on xml
*/
public List getTaglibs() throws JDOMException, IOException
{
SAXBuilder builder = new SAXBuilder();
Document doc = builder.build(new File(getPluginScript()));
XPath xpath = XPath.newInstance("/project/define:taglib");
List taglibElements = xpath.selectNodes(doc);
List taglibs = new LinkedList();
for (Iterator iter = taglibElements.iterator(); iter.hasNext();)
{
Element element = (Element) iter.next();
Map taglib = new HashMap();
taglib.put("uri", element.getAttributeValue("uri"));
taglib.put("tagNames", new LinkedList());
XPath tagsXp = XPath.newInstance("define:tag|define:jellybean");
List tagsElements = tagsXp.selectNodes(element);
for (Iterator tagsIter = tagsElements.iterator(); tagsIter.hasNext();)
{
Element tagsElement = (Element) tagsIter.next();
((List)
taglib.get("tagNames")).add(tagsElement.getAttributeValue("name"));
}
taglibs.add(taglib);
}
return taglibs;
}
}
1.1 maven-plugins/plugin/src/test/plugin.jelly
Index: plugin.jelly
===================================================================
<?xml version="1.0"?>
<!--
/*
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed 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.
*/
-->
<project xmlns:define="jelly:define"
xmlns:j="jelly:core"
xmlns:jsl="jelly:jsl"
xmlns:log="jelly:log"
xmlns:maven="jelly:maven"
xmlns:pom="pom"
xmlns:util="jelly:util"
xmlns:x="jelly:xml"
xmlns:velocity="jelly:velocity"
xmlns:doc="doc">
<j:new var="reports" className="java.util.ArrayList"/>
<define:taglib uri="doc">
<define:tag name="deregisterReport">
<!-- @name : Report to deregister, must be same as name used to register -->
<maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
<j:set var="removeRpt" value="null"/>
<j:forEach var="rpt" items="${reports}">
<j:if test="${rpt.get('name').equals(name)}">
<j:set var="removeRpt" value="${rpt}"/>
</j:if>
</j:forEach>
<j:if test="${removeRpt != null}">
<j:set var="dummy" value="${reports.remove(removeRpt)}"/>
</j:if>
</define:tag>
<define:tag name="registerReport">
<!--
@name the name of this report. Used for navigation items
@pluginName the name of the plugin. @plugin:report goal must exist
@description text description of report
@link the nav-bar link for this report
@target the target for the new page (_self, _blank, ...)
-->
<maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
<!-- check if the given name is in the list already -->
<j:set var="add" value="true"/>
<j:forEach var="rpt" items="${reports}">
<j:if test="${rpt.get('name').equals(name)}">
<j:set var="add" value="false"/>
</j:if>
</j:forEach>
<j:if test="${add.equals('true')}">
<j:new var="report" className="java.util.HashMap"/>
<j:set var="dummy">
${report.put('name', name)}
${report.put('pluginName', pluginName)}
${report.put('description', description)}
${report.put('link', link)}
${report.put('externalLink', externalLink)}
${report.put('target', target)}
${reports.add(report)}
</j:set>
</j:if>
</define:tag>
<define:tag name="formatAsNumber">
<!--
| @string
| @pattern
-->
<!-- This appears to need to be here which is no good. Need
more of a global tool box.
-->
<j:useBean var="formatter" class="org.apache.maven.util.DVSLFormatter"/>
${formatter.formatNumber(string,pattern)}
</define:tag>
<define:tag name="jslFile">
<!--
| Basic tag for performing arbitrary jsl transformations
| on arbitrary jsl inputs.
| @input (optional)
| @output
| @stylesheet
| @encoding
| @omitXmlDeclaration
| @outputMode
| @prettyPrint
-->
<!-- Set default encoding if not set. -->
<j:if test="${encoding == null}">
<j:set var="encoding"
value="${plugin.getVariable('maven.docs.outputencoding')}"/>
</j:if>
<j:if test="${input != null}">
<util:file name="${input}" var="inputFile" />
<x:parse var="doc" xml="${inputFile}"/>
</j:if>
<j:set var="stylesheetURI" value="file:${stylesheet}"/>
<j:file
name="${output}"
encoding="${encoding}"
omitXmlDeclaration="${omitXmlDeclaration}"
outputMode="${outputMode}"
prettyPrint="${prettyPrint}">
<j:include uri="${stylesheetURI.toString()}"/>
</j:file>
</define:tag>
<define:tag name="jsl">
<!--
| This tag has a lot of defaults suitable for transforming
| documents easily. See jslCore for a tag suitable for
| transforming documents how you want.
| @input
| @outputDirectory - Will be placed under ${maven.gen.docs}
| @stylesheet
| @encoding - defaults to ${maven.docs.outputencoding}
| @omitXmlDeclaration - defaults to ${maven.docs.omitXmlDeclaration}
| @outputMode
| @prettyPrint
-->
<!--
@todo make sure the output directory exists.
-->
<!-- Set default outputDirectory if not set. -->
<j:if test="${empty(outputDirectory)}">
<j:set var="outputDirectory" value="${maven.gen.docs}"
/>
</j:if>
<!-- Set default encoding if not set. -->
<j:if test="${encoding == null}">
<j:set var="encoding" value="${maven.docs.outputencoding}" />
</j:if>
<j:if test="${omitXmlDeclaration == null}">
<j:set var="omitXmlDeclaration" value="${maven.docs.omitXmlDeclaration}"/>
</j:if>
<mkdir dir="${outputDirectory}"/>
<doc:jslFile
input="${input}"
output="${outputDirectory}/${output}"
stylesheet="${stylesheet}"
encoding="${encoding}"
omitXmlDeclaration="${omitXmlDeclaration}"
outputMode="${outputMode}"
prettyPrint="${prettyPrint}"/>
</define:tag>
<!--
@link
@relativePath
@name
@img
@state - expanded / collapsed / none
@target
-->
<define:tag name="itemLink">
<x:element name="a">
<x:attribute
name="href">${pathTool.calculateLink(link,relativePath)}</x:attribute>
<j:choose>
<j:when test="${target != null and target.equals('_blank')}">
<x:attribute name="class">newWindow</x:attribute>
<x:attribute name="title">New Window</x:attribute>
</j:when>
<j:when test="${link.startsWith('http')}">
<x:attribute name="class">externalLink</x:attribute>
<x:attribute name="title">External Link</x:attribute>
</j:when>
</j:choose>
<j:if test="${!empty(target)}">
<x:attribute name="target">${target}</x:attribute>
</j:if>
<j:if test="${empty(state)}"><j:set var="state" value="none"/></j:if>
<j:if test="${empty(img)}">${name}</j:if>
<j:if test="${!empty(img)}"><img style="border: 1px"
src="${pathTool.calculateLink(img,relativePath)}" title="${name}"
alt="${name}"/></j:if>
</x:element>
</define:tag>
<define:tag name="text-xdoc">
<!--
@output - The output file
@title - Title for page
@section - Section heading
@encoding - The XML encoding
@preamble - Placed in paragraph block prior to text
@inputText - Will be wrapped in a CDATA, will not escape CDATA tags (as yet)
@inputFile - Will be read in and wrapped in CDATA. Overrides inputText if set
-->
<j:set var="inputFile">${inputFile}</j:set>
<j:if test="${inputFile != ''}">
<util:file name="${inputFile}" var="inputFileObject"/>
<util:loadText var="inputText" file="${inputFileObject}"/>
</j:if>
<!-- Set default encoding if not set. -->
<j:if test="${encoding == null}">
<j:set var="encoding"
value="${plugin.getVariable('maven.docs.outputencoding')}"/>
</j:if>
<j:file name="${output}" prettyPrint="false" encoding="${encoding}">
<document>
<properties><title>${title}</title></properties>
<body>
<section name="${section}">
<p>${preamble}</p>
<source>
<![CDATA[${inputText}]]>
</source>
</section>
</body>
</document>
</j:file>
</define:tag>
<!-- Alternator for row style in a table -->
<define:tag name="printRow">
<j:if test="${(count % 2) gt 0}">
<x:element name="tr">
<x:attribute name="class">a</x:attribute>
</x:element>
</j:if>
<j:if test="${(count % 2) le 0}">
<x:element name="tr">
<x:attribute name="class">b</x:attribute>
</x:element>
</j:if>
</define:tag>
<!-- Generates the JSL files on the given srcdir attribute -->
<define:tag name="performJSL">
<util:file var="srcdirFile" name="${srcdir}"/>
<j:set var="srcdir" value="${srcdirFile.getCanonicalPath()}"/>
<util:file var="destdirFile" name="${destdir}"/>
<j:set var="destdir" value="${destdirFile.getCanonicalPath()}"/>
<util:replace var="fromPattern" oldChar="\" newChar="/"
value="${srcdir}/*.xml"/>
<util:replace var="toPattern" oldChar="\" newChar="/"
value="${destdir}/*.html"/>
<j:if test="${mapper == null}">
<j:new var="mapper"
className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
</j:if>
<j:setProperties object="${mapper}" from="${fromPattern}" to="${toPattern}"/>
<util:replace var="fromDirPattern" oldChar="\" newChar="/" value="${srcdir}*"/>
<util:replace var="toDirPattern" oldChar="\" newChar="/" value="${destdir}*"/>
<j:new var="dirMapper"
className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
<j:setProperties object="${dirMapper}" from="${fromDirPattern}"
to="${toDirPattern}"/>
<fileScanner var="docFiles">
<fileset dir="${srcdir}">
<patternset>
<exclude name="**/project.xml"/>
<exclude name="**/template.xml"/>
<exclude name="**/navigation.xml"/>
<exclude name="changes.xml"/>
<include name="**/*.xml"/>
</patternset>
</fileset>
</fileScanner>
<!-- determine nav file to be used:- 1. check for sitewide nav files -->
<!-- supplied nav file as project.xml in stylesheets dir -->
<util:available file="${maven.docs.src}/stylesheets/project.xml">
<util:file var="siteNavFile"
name="${maven.docs.src}/stylesheets/project.xml"/>
</util:available>
<!-- supplied nav file as project.xml in root of xdocs source tree -->
<util:available file="${maven.docs.src}/project.xml">
<util:file var="siteNavFile" name="${maven.docs.src}/project.xml"/>
</util:available>
<!-- supplied navigation file in root of xdocs source tree -->
<util:available file="${maven.docs.src}/navigation.xml">
<util:file var="siteNavFile" name="${maven.docs.src}/navigation.xml"/>
</util:available>
<!-- navigation file that was generated -->
<util:available file="${maven.gen.docs}/navigation.xml">
<util:file var="siteNavFile" name="${maven.gen.docs}/navigation.xml"/>
</util:available>
<!-- hold onto maven.docs.src for later -->
<util:file var="docsSrcFile" name="${maven.docs.src}"/>
<!-- parse the project nav. Someone jellier than me can remove the temp file
requirement -->
<maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
<util:file var="tempnav" name="${maven.build.dir}/project-nav.xml"/>
<j:file name="${tempnav.toString()}" outputMode="xml">
<j:import file="${plugin.resources}/navigation.jelly" inherit="true"/>
</j:file>
<x:parse var="projectNavRoot" xml="${tempnav}"/>
<x:set var="projectNav" select="$projectNavRoot/project"/>
<j:forEach var="file" items="${docFiles.iterator()}">
<util:replace var="inDirForward" oldChar="\" newChar="/"
value="${file.parent}"/>
<j:set var="outDir" value="${dirMapper.mapFileName(inDirForward).0}"/>
<mkdir dir="${outDir}"/>
<!-- generate output file name -->
<util:replace var="outFileForward" oldChar="\" newChar="/"
value="${file.toString()}"/>
<j:set var="outFile" value="${mapper.mapFileName(outFileForward).0}"/>
<echo>Generating ${outFile} from ${file}</echo>
<!-- work out relative path -->
<util:replace var="docsForward" oldChar="\" newChar="/" value="${srcdir}"/>
<j:if test="${pathTool == null}">
<j:useBean var="pathTool" class="org.apache.maven.util.DVSLPathTool"/>
</j:if>
<j:set var="relativePath" value="${pathTool.getRelativePath(docsForward,
outFileForward)}"/>
<!-- determine nav file to be used: 2. check for nav file -->
<!-- in the same directory as xml file being processed -->
<!-- if no such nav file available use sitewide nav file -->
<j:set var="navFile" value="${siteNavFile}" />
<util:available file="${file.parentFile.absoluteFile}/navigation.xml">
<!-- dont use current directory navigation.xml if it's in maven.docs.src
-->
<j:if test="${!(file.parentFile.equals(docsSrcFile))}">
<util:file var="navFile"
name="${file.parentFile.absoluteFile}/navigation.xml"/>
</j:if>
</util:available>
<!-- parse nav and make it available to the stylesheet -->
<x:parse var="navXML" xml="${navFile}"/>
<x:set var="nav" select="$navXML/project"/>
<!-- parse the doc and pass it to the stylesheet -->
<x:parse var="doc" xml="${file}"/>
<j:file name="${outFile}" encoding="${outputencoding}"
omitXmlDeclaration="true" outputMode="xml"
prettyPrint="no">
<j:include uri="${stylesheet.toString()}"/>
</j:file>
</j:forEach>
</define:tag>
<define:tag name="jslToSite">
<!--
| transforms files in the given dir using the site stylesheet and
navigation and place them
| in maven.docs.dest (typically target/docs)
| @srcdir source directory
-->
<maven:param-check value="${srcdir}" fail="true" message="'srcdir' must be
specified"/>
<maven:pluginVar var="maven.xdoc.jsl"
plugin='maven-xdoc-plugin' property='maven.xdoc.jsl' />
<!-- copy old value for restoring it later -->
<j:set var="previous.plugin.resources" value="${plugin.resources}" />
<maven:pluginVar var="plugin.resources"
plugin='maven-xdoc-plugin' property='plugin.resources' />
<maven:pluginVar var="includeProjectDocumentation"
plugin='maven-xdoc-plugin' property='maven.xdoc.includeProjectDocumentation'
/>
<maven:pluginVar var="maven.xdoc.poweredby.image"
plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.image' />
<maven:pluginVar var="maven.xdoc.poweredby.title"
plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.title' />
<maven:pluginVar var="maven.xdoc.poweredby.url"
plugin='maven-xdoc-plugin' property='maven.xdoc.poweredby.url' />
<maven:pluginVar var="maven.xdoc.crumb.separator"
plugin='maven-xdoc-plugin' property='maven.xdoc.crumb.separator' />
<j:set var="outputDirectory" value="${maven.gen.docs}" />
<j:set var="stylesheet" value="file:${plugin.resources}/site.jsl" />
<j:set var="outputencoding" value="${maven.docs.outputencoding}" />
<doc:performJSL srcdir="${srcdir}" destdir="${maven.docs.dest}" />
<!-- restore plugin.resources -->
<j:set var="plugin.resources" value="${previous.plugin.resources}" />
</define:tag>
<!--
| escapes a string for generating a valid name token (need for "name" attribute
in html anchors)
| @value given token
-->
<define:tag name="escapeNameToken">
<j:invokeStatic var="escapedtoken"
className="org.apache.commons.lang.StringUtils" method="replaceChars">
<j:arg type="java.lang.String" value="${value}"
useContextClassLoader="true"/>
<j:arg type="java.lang.String" value=" .,;!?/'\()[]{}+*°"
useContextClassLoader="true"/>
<j:arg type="java.lang.String" value="__________________"
useContextClassLoader="true"/>
</j:invokeStatic>${escapedtoken}</define:tag>
</define:taglib>
<!-- ================================================================== -->
<!-- P R O J E C T D O C U M E N T A T I O N -->
<!-- ================================================================== -->
<goal name="xdoc"
prereqs="xdoc:generate-from-pom, xdoc:transform"
description="Generate html project documentation xdoc sources"/>
<goal name="xdoc:init"
description="Generates the directory structure required for xdocs">
<mkdir dir="${maven.gen.docs}"/>
<mkdir dir="${maven.docs.dest}"/>
</goal>
<goal
name="xdoc:generate-from-pom"
prereqs="xdoc:init, xdoc:register-reports"
description="Generates xdocs for site based on project descriptor">
<echo>Generating xdocs from POM ... </echo>
<util:tokenize var="pomDocuments"
delim=",">${maven.xdoc.pomDocuments}</util:tokenize>
<!-- All the templates use $project for now. -->
<j:set var="project" value="${pom}"/>
<maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
<!-- Does the user want the maven-generated docs on their site? -->
<j:set
var="includeProjectDocumentation"
value="${maven.xdoc.includeProjectDocumentation}"/>
<!-- Need the escaper to html output. -->
<j:useBean var="escape" class="org.apache.velocity.anakia.Escape"/>
<j:useBean var="files" class="org.apache.velocity.texen.util.FileUtil"/>
<!-- Need to enrich information about dependency by taking some information from
its POM. -->
<j:useBean var="dependencyDescriber"
class="org.apache.maven.DependencyDescriberBean"/>
${dependencyDescriber.build(pom)}
<j:if test="${encoding == null}">
<j:set
var="encoding"
value="${maven.docs.outputencoding}"
/>
</j:if>
<j:forEach var="pomDocument" items="${pomDocuments}">
<!-- If the template ends with ".xml" use velocity to generate the
HTML. If it ends with ".jelly" use JSL. -->
<j:choose>
<j:when test="${pomDocument.endsWith('.xml')}">
<velocity:merge
name="${maven.gen.docs}/${pomDocument}"
basedir="${plugin.resources}/templates"
template="${pomDocument}"
inputEncoding="${encoding}"
outputEncoding="${encoding}"
/>
</j:when>
<j:when test="${pomDocument.endsWith('.jelly')}">
<doc:jslFile
output="${maven.gen.docs}/${pomDocument.substring(0,pomDocument.indexOf('.jelly'))}.xml"
stylesheet="${plugin.resources}/templates/${pomDocument}"
outputMode="xml"
prettyPrint="true"/>
</j:when>
<j:otherwise>
<fail>Unknown report format for report [${pomDocument}].</fail>
</j:otherwise>
</j:choose>
</j:forEach>
</goal>
<!-- ================================================================== -->
<!-- V A L I D A T E X D O C S -->
<!-- ================================================================== -->
<!-- validate xdocs -->
<goal name="xdoc:validate" prereqs="pom:taglib"
description="Validate xdocs match the schema">
<available file="${maven.docs.src}" type="dir"
property="maven.docs.src.available"/>
<j:if test="${maven.docs.src.available}">
<fileScanner var="navFiles">
<fileset dir="${maven.docs.src}">
<patternset>
<include name="**/navigation.xml"/>
</patternset>
</fileset>
</fileScanner>
<j:forEach var="file" items="${navFiles.iterator()}">
<echo>Validating ${file}</echo>
<pom:validate validator="${maven.home}/maven-navigation-1.0.xsd"
projectDescriptor="${file}"/>
</j:forEach>
</j:if>
</goal>
<!-- ================================================================== -->
<!-- C O P Y R E S O U R C E S -->
<!-- ================================================================== -->
<!-- copy resources needed for xdocs -->
<goal name="xdoc:copy-resources"
prereqs="xdoc:init"
description="copy static resources for use in xdocs generated html">
<!-- Read in the ui properties. -->
<util:properties uri="file:${plugin.resources}/ui.properties"
var="uiProperties"/>
<!-- Copy maven supplied stylesheets. -->
<copy todir="${maven.docs.dest}/style" overwrite="yes" filtering="yes">
<fileset dir="${plugin.resources}/css">
<include name="**/*.css"/>
</fileset>
<filterset>
<j:forEach var="uiProperty" items="${uiProperties.keys()}">
<util:replace var="token" oldChar="." newChar="_" value="${uiProperty}"/>
<j:set var="token" value="${token.substring(6).toUpperCase()}"/>
<!-- Check if User has overidden this property -->
<j:set var="propertyName" value="${uiProperty}" />
<j:set var="propertyValue" value="${context.getVariable(propertyName)}"/>
<j:choose>
<j:when test="${propertyValue != null}">
<!-- Use user's properties -->
<filter token="${token}" value="${propertyValue}"/>
</j:when>
<j:otherwise>
<!-- Use plugin's default properties -->
<filter token="${token}"
value="${uiProperties.getProperty(uiProperty)}"/>
</j:otherwise>
</j:choose>
</j:forEach>
</filterset>
</copy>
<!-- Copy maven supplied images. -->
<copy todir="${maven.docs.dest}/images" overwrite="yes" filtering="no">
<fileset dir="${plugin.resources}/images">
<include name="**/*.gif"/>
<include name="**/*.jpeg"/>
<include name="**/*.jpg"/>
<include name="**/*.png"/>
</fileset>
</copy>
</goal>
<!-- ================================================================== -->
<!-- C O P Y U S E R S U P P L I E D R E S O U R C E S -->
<!-- ================================================================== -->
<!-- copy user resources -->
<goal name="xdoc:copy-user-resources"
prereqs="xdoc:init"
description="Copy user provided resources to docs destination">
<j:if test="${maven.docs.src.available}">
<!-- Copy user supplied resources -->
<copy todir="${maven.docs.dest}" filtering="no">
<fileset dir="${maven.docs.src}">
<exclude name="**/*.xml"/>
<exclude name="**/*.fml"/>
<exclude name="**/CVS/*"/>
<exclude name="stylesheets/*"/>
</fileset>
<!-- copy file in generated docs folder: this allows for reporting plugins
to add images -->
<fileset dir="${maven.gen.docs}">
<exclude name="**/*.xml"/>
<exclude name="**/CVS/*"/>
<exclude name="stylesheets/*"/>
</fileset>
</copy>
<util:available file="${maven.docs.src}/stylesheets">
<!-- Copy user supplied stylesheets, can override maven -->
<copy todir="${maven.docs.dest}/style" overwrite="true" filtering="no">
<fileset dir="${maven.docs.src}/stylesheets">
<include name="**/*.css"/>
</fileset>
</copy>
</util:available>
</j:if>
</goal>
<!-- ================================================================== -->
<!-- D V S L D O C U M E N T A T I O N -->
<!-- ================================================================== -->
<goal name="xdoc:transform"
prereqs="xdoc:init"
description="Generate html project documentation xdoc sources">
<tstamp>
<format property="mavenCurrentYear" pattern="yyyy"/>
</tstamp>
<!-- Use jelly utils here -->
<available
file="${maven.gen.docs}"
type="dir"
property="maven.gen.docs.available"
/>
<available
file="${maven.docs.src}"
type="dir"
property="maven.docs.src.available"
/>
<!-- use JSL in Jelly to build the documenation -->
<attainGoal name="xdoc:copy-resources"/>
<attainGoal name="xdoc:copy-user-resources"/>
<attainGoal name="xdoc:jelly-transform"/>
</goal>
<!-- ================================================================== -->
<!-- J E L L Y D O C U M E N T A T I O N -->
<!-- ================================================================== -->
<goal name="xdoc:jelly-init" description="Set up jelly xdoc requirements">
<!-- moving here temporarily -->
<tstamp>
<format property="mavenCurrentYear" pattern="yyyy"/>
</tstamp>
<tstamp>
<format property="build.date" pattern="${maven.xdoc.date.format}"
locale="${maven.xdoc.date.locale}"/>
</tstamp>
</goal>
<goal name="xdoc:register-reports">
<!--
| We need to have each <report> register itself with us so we can
| build up our navbar. To do this, we call the plugin:register
| goal on each report plugin.
|-->
<j:if test="${!pom.reports.isEmpty()}">
<j:forEach var="report" items="${pom.reports}">
<attainGoal name="${report}:register"/>
</j:forEach>
</j:if>
<!-- If the descriptor is empty, use these as defaults -->
<j:if test="${pom.reports.isEmpty()}">
<attainGoal name="maven-jdepend-plugin:register"/>
<attainGoal name="maven-checkstyle-plugin:register"/>
<attainGoal name="maven-changes-plugin:register"/>
<attainGoal name="maven-changelog-plugin:register"/>
<attainGoal name="maven-developer-activity-plugin:register"/>
<attainGoal name="maven-file-activity-plugin:register"/>
<attainGoal name="maven-license-plugin:register"/>
<attainGoal name="maven-javadoc-plugin:register"/>
<attainGoal name="maven-jxr-plugin:register"/>
<attainGoal name="maven-junit-report-plugin:register"/>
<attainGoal name="maven-linkcheck-plugin:register"/>
<attainGoal name="maven-tasklist-plugin:register"/>
</j:if>
</goal>
<goal name="xdoc:jelly-transform"
prereqs="xdoc:init, xdoc:jelly-init, xdoc:register-reports"
description="transform xdocs using jelly/jsl rather than dvsl">
<j:set var="destdir" value="${maven.docs.dest}"/>
<j:set var="outputencoding" value="${maven.docs.outputencoding}"/>
<!-- need to parse navigation into $nav -->
<!-- mapper for determining output file name -->
<j:new var="mapper"
className="org.apache.maven.util.CaseInsensitiveGlobPatternMapper"/>
<!-- path tool for relative processing -->
<j:useBean var="pathTool" class="org.apache.maven.util.DVSLPathTool"/>
<!-- tool for loading resources from the class loader -->
<j:useBean class="org.apache.maven.util.ResourceBean" var="resourceTool"/>
<!-- determine which stylesheet to use -->
<j:set var="stylesheet" value="${maven.xdoc.jsl}"/>
<j:if test="${empty(stylesheet)}">
<j:set var="stylesheet"
value="${resourceTool.findResource('plugin-resources/site.jsl')}"/>
<j:if test="${empty(stylesheet)}">
<log:warn>Could not load the JSL stylesheet 'site.jsl' on the
classpath</log:warn>
<j:set var="stylesheet" value="./site.jsl"/>
</j:if>
</j:if>
<util:available file="${maven.gen.docs}">
<log:info>About to use JSL stylesheet ${stylesheet}</log:info>
<!-- perform JSL on generated docs -->
<doc:performJSL srcdir="${maven.gen.docs}" destdir="${maven.docs.dest}"/>
</util:available>
<!-- perform JSL on user provided docs -->
<j:if test="${maven.docs.src.available}">
<log:info>
Transforming user supplied documentation.
</log:info>
<doc:performJSL srcdir="${maven.docs.src}" destdir="${maven.docs.dest}"/>
</j:if>
</goal>
<!--
! This is required as the linkchecker runs as a final pass over the generated
! document tree.
! FIXME: Why isn't this in linkcheck?
!-->
<goal name="xdoc:performJSL"
description="Allows the LinkCheck plugin to xdoc a single directory">
<maven:pluginVar var="maven.xdoc.src" plugin="maven-linkcheck-plugin"
property="maven.xdoc.src" />
<doc:performJSL
srcdir="${maven.xdoc.src}"
destdir="${maven.docs.dest}"/>
</goal>
<goal name="xdoc:dump-report-settings">
<echo>Dumping report settings</echo>
<maven:pluginVar var="reports" plugin="maven-xdoc-plugin" property="reports" />
<j:forEach var="report" items="${reports}">
<echo>Report: ${report}</echo>
</j:forEach>
</goal>
</project>
1.45 +33 -0 maven-plugins/plugin/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/maven-plugins/plugin/project.xml,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -r1.44 -r1.45
--- project.xml 15 Jul 2004 00:17:52 -0000 1.44
+++ project.xml 18 Jul 2004 14:20:03 -0000 1.45
@@ -92,6 +92,12 @@
</developers>
<dependencies>
<dependency>
+ <groupId>commons-lang</groupId>
+ <artifactId>commons-lang</artifactId>
+ <version>2.0</version>
+ <url>http://jakarta.apache.org/commons/lang/</url>
+ </dependency>
+ <dependency>
<groupId>commons-jelly</groupId>
<artifactId>commons-jelly-tags-xml</artifactId>
<version>20040613.030723</version>
@@ -102,5 +108,32 @@
<artifactId>commons-jelly-tags-interaction</artifactId>
<version>20030211.143817</version>
</dependency>
+ <dependency>
+ <groupId>jdom</groupId>
+ <artifactId>jdom</artifactId>
+ <version>b10</version>
+ </dependency>
+ <dependency>
+ <groupId>saxpath</groupId>
+ <artifactId>saxpath</artifactId>
+ <version>1.0-FCS</version>
+ </dependency>
+ <dependency>
+ <groupId>jaxen</groupId>
+ <artifactId>jaxen</artifactId>
+ <version>1.0-FCS-full</version>
+ </dependency>
+ <dependency>
+ <groupId>xml-apis</groupId>
+ <artifactId>xml-apis</artifactId>
+ <version>1.0.b2</version>
+ <url>http://xml.apache.org/xerces2-j/</url>
+ </dependency>
+ <dependency>
+ <id>xerces</id>
+ <version>2.4.0</version>
+ <url>http://xml.apache.org/xerces2-j/</url>
+ </dependency>
</dependencies>
</project>
+
1.43 +38 -0 maven-plugins/plugin/plugin.jelly
Index: plugin.jelly
===================================================================
RCS file: /home/cvs/maven-plugins/plugin/plugin.jelly,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -r1.42 -r1.43
--- plugin.jelly 11 Jul 2004 00:57:59 -0000 1.42
+++ plugin.jelly 18 Jul 2004 14:20:03 -0000 1.43
@@ -93,6 +93,7 @@
<attainGoal name="plugin:generate-navigation" />
<attainGoal name="plugin:generate-goals" />
<attainGoal name="plugin:generate-properties" />
+ <attainGoal name="plugin:generate-tags" />
</goal>
<!-- generate a skeletal navigation.xml for the plugin specified
@@ -198,6 +199,43 @@
</j:if>
</goal>
+ <!-- generate a skeletal tags.xml for the plugin specified -->
+ <goal name="plugin:generate-tags"
+ description="Generate tags.xml for the plugin">
+
+ <j:set var="skip" value="false" />
+ <j:set var="fileName">${maven.docs.src}/tags.xml</j:set>
+ <u:available file="${fileName}">
+ <echo>Skipping file as '${fileName}' already exists</echo>
+ <j:set var="skip" value="true" />
+ </u:available>
+
+ <j:if test="${!skip}">
+ <j:set var="pluginScript" value="false" />
+ <u:available file="${basedir}/plugin.jelly">
+ <j:set var="pluginScript" value="true" />
+ </u:available>
+
+ <mkdir dir="${maven.docs.src}" />
+
+ <j:if test="${!pluginScript}">
+ <!-- no plugin.jelly - generate a file for empty goals -->
+ <echo>No plugin.jelly, not generating tags.xml</echo>
+ </j:if>
+
+ <j:if test="${pluginScript}">
+ <echo>Generating file '${fileName}'</echo>
+ <!-- generate docs based on plugin.jelly -->
+ <j:useBean class="org.apache.maven.plugin.PluginToTags"
+ pluginScript="${basedir}/plugin.jelly"
+ xdoc="${fileName}"
+ var="xformer"/>
+ ${xformer.transform()}
+ </j:if>
+
+ </j:if>
+ </goal>
+
<goal name="plugin:download" description="download and install a plugin from a
remote repo" prereqs="plugin:download-artifact">
<plugin:uninstall name="${artifactId}" />
<u:file var="localPlugin"
name="${maven.plugin.dir}/${artifactId}-${version}.jar" />
1.1
maven-plugins/plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java
Index: PluginToTagsTest.java
===================================================================
package org.apache.maven.plugin;
/*
* ====================================================================
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed 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.
* ====================================================================
*/
import junit.framework.TestCase;
import org.jdom.JDOMException;
import java.io.File;
import java.io.IOException;
import java.util.Map;
/**
* @author Dion Gillard
*/
public class PluginToTagsTest extends TestCase
{
private static final String basedir = System.getProperty("basedir");
/**
* test the right taglibs are found
* @throws JDOMException
* @throws IOException
*/
public void testTaglibs() throws JDOMException, IOException
{
PluginToTags instance = new PluginToTags();
testBasedir();
instance.setPluginScript(basedir + "/src/test/plugin.jelly");
assertEquals("wrong number of taglibs", 1, instance.getTaglibs().size());
Map taglib = (Map)instance.getTaglibs().get(0);
assertEquals("bad taglib uri", "doc", taglib.get("uri"));
}
/**
* test that basedir is passed in
*/
public void testBasedir()
{
assertNotNull("no basedir", basedir);
}
/**
* test the taglibs are written as a file
* @throws JDOMException
* @throws IOException
*/
public void testTransform() throws JDOMException, IOException
{
PluginToTags instance = new PluginToTags();
testBasedir();
instance.setPluginScript(basedir + "/src/test/plugin.jelly");
instance.setXdoc(basedir + "/target/tags.xml");
instance.transform();
File outputFile = new File(instance.getXdoc());
assertTrue("xdoc not generated", outputFile.exists());
}
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
