From a7c9c041735a112a7b6600fa047150009efbc65f Mon Sep 17 00:00:00 2001 From: dion Date: Sun, 18 Jul 2004 14:20:03 +0000 Subject: [PATCH] Add the ability to generate a skeletal doc on the taglib(s) provided by plugins git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@115847 13f79535-47bb-0310-9956-ffa450edef68 --- plugin/plugin.jelly | 38 + plugin/project.xml | 33 + .../org/apache/maven/plugin/PluginToTags.java | 197 +++++ plugin/src/plugin-test/maven.xml | 2 +- plugin/src/plugin-test/plugin.jelly | 1 + .../apache/maven/plugin/PluginToTagsTest.java | 75 ++ plugin/src/test/plugin.jelly | 778 ++++++++++++++++++ plugin/xdocs/navigation.xml | 1 + plugin/xdocs/tags.xml | 113 +++ 9 files changed, 1237 insertions(+), 1 deletion(-) create mode 100644 plugin/src/main/org/apache/maven/plugin/PluginToTags.java create mode 100644 plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java create mode 100644 plugin/src/test/plugin.jelly create mode 100644 plugin/xdocs/tags.xml diff --git a/plugin/plugin.jelly b/plugin/plugin.jelly index d06d5384..43ea887e 100644 --- a/plugin/plugin.jelly +++ b/plugin/plugin.jelly @@ -93,6 +93,7 @@ + + + + + ${maven.docs.src}/tags.xml + + Skipping file as '${fileName}' already exists + + + + + + + + + + + + + + No plugin.jelly, not generating tags.xml + + + + Generating file '${fileName}' + + + ${xformer.transform()} + + + + + diff --git a/plugin/project.xml b/plugin/project.xml index c48a67a0..b26eabe7 100644 --- a/plugin/project.xml +++ b/plugin/project.xml @@ -91,6 +91,12 @@ + + commons-lang + commons-lang + 2.0 + http://jakarta.apache.org/commons/lang/ + commons-jelly commons-jelly-tags-xml @@ -102,5 +108,32 @@ commons-jelly-tags-interaction 20030211.143817 + + jdom + jdom + b10 + + + saxpath + saxpath + 1.0-FCS + + + jaxen + jaxen + 1.0-FCS-full + + + xml-apis + xml-apis + 1.0.b2 + http://xml.apache.org/xerces2-j/ + + + xerces + 2.4.0 + http://xml.apache.org/xerces2-j/ + + diff --git a/plugin/src/main/org/apache/maven/plugin/PluginToTags.java b/plugin/src/main/org/apache/maven/plugin/PluginToTags.java new file mode 100644 index 00000000..a7657fa5 --- /dev/null +++ b/plugin/src/main/org/apache/maven/plugin/PluginToTags.java @@ -0,0 +1,197 @@ +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("\n"); + bw.write(" \n"); + bw.write(" Plugin tags\n"); + bw.write(" \n"); + bw.write(" \n"); + List taglibs = getTaglibs(); + writeOverview(bw, taglibs); + writeTaglibs(bw, taglibs); + bw.write(" \n"); + bw.write("\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("
\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(" \n"); + bw.write("

No description

\n"); + bw.write(" \n"); + bw.write(" \n"); + bw.write("
AttributeOptional?Description
\n"); + bw.write(" \n"); + } + bw.write("
\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("
\n"); + bw.write("

The following tag libraries and tags are provided by this plugin.

\n"); + bw.write("
    \n"); + for (Iterator taglibIter = taglibs.iterator(); taglibIter.hasNext();) + { + Map taglib = (Map) taglibIter.next(); + String title = taglib.get("uri") + " Tag Library"; + String linkStart = ""; + bw.write("
  1. " + linkStart + taglib.get("uri") + "\n"); + bw.write("
      \n"); + List tagNames = (List)taglib.get("tagNames"); + for (Iterator tagIter = tagNames.iterator(); tagIter.hasNext();) + { + String name = (String) tagIter.next(); + bw.write("
    1. " + name + "
      2. \n"); + } + bw.write("
    \n"); + bw.write("
    2. \n"); + } + bw.write("
\n"); + bw.write("
\n"); + } + + /** + * @return a list of tag libraries. Each element in the list + * is a {@link 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; + } + +} \ No newline at end of file diff --git a/plugin/src/plugin-test/maven.xml b/plugin/src/plugin-test/maven.xml index 06ff0961..a6166eae 100644 --- a/plugin/src/plugin-test/maven.xml +++ b/plugin/src/plugin-test/maven.xml @@ -28,7 +28,7 @@ - navigation.xml,goals.xml + navigation.xml,goals.xml,properties.xml,tags.xml diff --git a/plugin/src/plugin-test/plugin.jelly b/plugin/src/plugin-test/plugin.jelly index aa0fceee..3a6199cc 100644 --- a/plugin/src/plugin-test/plugin.jelly +++ b/plugin/src/plugin-test/plugin.jelly @@ -20,6 +20,7 @@ + diff --git a/plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java b/plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java new file mode 100644 index 00000000..845dfadc --- /dev/null +++ b/plugin/src/test/org/apache/maven/plugin/PluginToTagsTest.java @@ -0,0 +1,75 @@ +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()); + } + + +} diff --git a/plugin/src/test/plugin.jelly b/plugin/src/test/plugin.jelly new file mode 100644 index 00000000..4b3fcdac --- /dev/null +++ b/plugin/src/test/plugin.jelly @@ -0,0 +1,778 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ${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)} + + + + + + + + + + + + ${formatter.formatNumber(string,pattern)} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ${pathTool.calculateLink(link,relativePath)} + + + newWindow + New Window + + + externalLink + External Link + + + + ${target} + + + ${name} + ${name} + + + + + + ${inputFile} + + + + + + + + + + + + + + ${title} + +
+

${preamble}

+ + + +
+ + + + + + + + + + a + + + + + b + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Generating ${outFile} from ${file} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ${escapedtoken} + + + + + + + + + + + + + + + + + + + Generating xdocs from POM ... + + ${maven.xdoc.pomDocuments} + + + + + + + + + + + + + + + ${dependencyDescriber.build(pom)} + + + + + + + + + + + + + + + + + + Unknown report format for report [${pomDocument}]. + + + + + + + + + + + + + + + + + + + + + + + + + + + Validating ${file} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Could not load the JSL stylesheet 'site.jsl' on the classpath + + + + + + About to use JSL stylesheet ${stylesheet} + + + + + + + + + Transforming user supplied documentation. + + + + + + + + + + + + + + + + Dumping report settings + + + + Report: ${report} + + + + diff --git a/plugin/xdocs/navigation.xml b/plugin/xdocs/navigation.xml index d63edbca..e9229ae4 100644 --- a/plugin/xdocs/navigation.xml +++ b/plugin/xdocs/navigation.xml @@ -27,6 +27,7 @@ + \ No newline at end of file diff --git a/plugin/xdocs/tags.xml b/plugin/xdocs/tags.xml new file mode 100644 index 00000000..927c3565 --- /dev/null +++ b/plugin/xdocs/tags.xml @@ -0,0 +1,113 @@ + + + Plugin tags + dIon Gillard + + +
+

The following tag libraries and tags are provided by this plugin.

+
    +
  1. plugin +
      +
    1. uninstall
      2. +
    2. clearCache
      3. +
    +
    2. +
  2. assert +
      +
    1. assertFileExists
      2. +
    2. assertFileNotFound
      3. +
    3. assertEquals
      4. +
    +
    3. +
+
+ +
+ +

+ A tag to uninstall a given plugin from the various plugin directories, including +

    +
  1. ${maven.plugin.dir}
    2. +
  2. ${maven.plugin.user.dir}
    3. +
  3. ${maven.plugin.unpacked.dir}
    4. +
+

+ + + + + + + +
AttributeOptional?Description
nameNoUsually this is ${pom.artifactId}
+ + +

+ Clears the files used for caching plugin goals, dependencies and + tag libraries from ${maven.plugin.unpacked.dir} +

+

There are no attributes for this tag

+ +
+
+

+ This tag library is typically used in testing plugins. And are + similar in usage to the assert methods in a JUnit test case. +

+ +

Fails the build if the given file does not exist, otherwise no effect.

+ + + + + + + + + + + + +
AttributeOptional?Description
fileNoThe path of the file to be checked
msgYesA message to be displayed when the file doesn't exist
+ + +

Fails the build if the given file does exist, otherwise no effect.

+ + + + + + + + + + + + +
AttributeOptional?Description
fileNoThe path of the file to be checked
msgYesA message to be displayed when the file doesn't exist
+ + +

Fails the build if the two values are not equal, otherwise no effect.

+ + + + + + + + + + + + + + + + + +
AttributeOptional?Description
expectedNoThe expected value
valueNoThe actual value
msgYesA message to be displayed when the values aren't equal.
+ +
+ +