- Added new download report along with a new link in the Maven generated documentation. This new link will only appear if you have defined the new <code>maven.xdoc.distributionUrl</code> property. There is also a new <code>maven.xdoc.distributionType</code> property that indicates what type of artifact your project is delivering. It defaults to "jar".

- The xdoc plugin now supports generating custom reports using Jelly. It was previously only supporting Velocity. Simply name your report templates with a ".jelly" extension.


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

xdoc/plugin.jelly

@@ -97,7 +97,7 @@
       <!--
        | Basic tag for performing arbitrary jsl transformations
        | on arbitrary jsl inputs.
-       | @input
+       | @input (optional)
        | @output
        | @stylesheet
        | @encoding
@@ -112,8 +112,10 @@
                value="${plugin.getVariable('maven.docs.outputencoding')}"/>
       </j:if>
 
-      <util:file name="${input}" var="inputFile" />
+      <j:if test="${input != null}">    
-      <x:parse var="doc" xml="${inputFile}"/>
+        <util:file name="${input}" var="inputFile" />
+        <x:parse var="doc" xml="${inputFile}"/>
+      </j:if>
       
       <j:set var="stylesheetURI" value="file:${stylesheet}"/>
       <j:file
@@ -458,13 +460,30 @@
     </j:if>
     
     <j:forEach var="pomDocument" items="${pomDocuments}">
-      <velocity:merge 
+
-        name="${maven.gen.docs}/${pomDocument}"
+      <!-- If the template ends with ".xml" use velocity to generate the 
-        basedir="${plugin.resources}/templates"
+           HTML. If it ends with ".jelly" use JSL. -->
-        template="${pomDocument}"
+      <j:choose>
-        inputEncoding="${encoding}"
+        <j:when test="${pomDocument.endsWith('.xml')}">
-        outputEncoding="${encoding}" 
+          <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>
 

xdoc/plugin.properties

@@ -26,12 +26,26 @@ maven.xdoc.includeProjectDocumentation = yes
 maven.xdoc.crumb.separator=|
 maven.xdoc.theme.url=
 
+# Location where the artifacts are distributed. This property is optional. 
+# If it is not defined, then the Download report will not be added to the 
+# navigation menu.
+# NOTE: In the future this information will be described in the POM
+# Ex: maven.xdoc.distributionUrl=http://www.ibiblio.org/maven/maven/plugins
+
+# Type of the distributed artifact. Defaults to jar. Override this property if
+# your project is distributing artifacts of a different type.
+# NOTE: In the future this information will be described in the POM
+maven.xdoc.distributionType=jar
+
 #
 # DATE Preferences
 #
+
 # The place of the date on the pages : choices are 'bottom', 'left', 'right', 'navigation-top', 'navigation-bottom'
 maven.xdoc.date = 
+
 maven.xdoc.date.format = dd MMMM yyyy
+
 # The date locale
 maven.xdoc.date.locale = en
 
@@ -97,12 +111,13 @@ maven.xdoc.pomDocuments = cvs-usage.xml,\
                           issue-tracking.xml,\
                           mail-lists.xml,\
                           project-info.xml,\
-                          team-list.xml
+                          team-list.xml,\
+                          downloads.jelly
                           
 maven.xdoc.projectInfo = cvs-usage.xml,\
-                          dependencies.xml,\
+                         dependencies.xml,\
-                          issue-tracking.xml,\
+                         issue-tracking.xml,\
-                          mail-lists.xml,\
+                         mail-lists.xml,\
-                          project-info.xml,\
+                         project-info.xml,\
-                          team-list.xml
+                         team-list.xml,\
-
+                         downloads.jelly

xdoc/src/plugin-resources/navigation.jelly

@@ -29,6 +29,12 @@
           <menu name="Project Documentation">
             <item name="About ${pom.name}" href="/index.html"/>   
 
+            <!-- Only display a "Downloads" menu link if the 
+                 maven.xdoc.distributionUrl has been defined -->
+            <j:if test="${context.getVariable('maven.xdoc.distributionUrl') != null}">
+              <item name="Downloads" href="/downloads.html"/>
+            </j:if>
+                        
             <item name="Project Info" href="/project-info.html" collapse="true">
               <item name="Mailing Lists" href="/mail-lists.html"/>
               <item name="Project Team" href="/team-list.html"/>

xdoc/src/plugin-resources/templates/downloads.jelly

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+ * ========================================================================
+ * 
+ * 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:j="jelly:core"
+  xmlns:maven="jelly:maven"
+  xmlns:util="jelly:util"
+  xmlns:x="jelly:xml">
+
+  <document>
+  
+    <properties>
+      <title>Downloads</title>
+    </properties>
+
+    <body>
+      <section name="Downloads">
+
+        <!-- Do not generate the report if the maven.xdoc.distributionUrl 
+             property is not defined -->
+        <j:choose>
+
+          <j:when test="${context.getVariable('maven.xdoc.distributionUrl') == null}">
+            <p>
+              You must define the <code>maven.xdoc.distributionUrl</code> 
+              property if you wish to generate the download report.
+            </p>
+          </j:when>
+  
+          <j:otherwise>
+
+            <j:choose>
+              <j:when test="${size(pom.versions) == 0}">
+                <p>
+                  This project has not released any version yet.
+                </p>
+              </j:when>
+              <j:otherwise>
+                <!-- Find list of versions by looking up the <version> element 
+                     in the POM -->
+                <p>
+                  List of available downloads.
+                </p>
+                <table>
+                  <tr>
+                    <th>Download links</th>
+                  </tr>
+                  <j:forEach var="version" items="${pom.versions}">
+                    <!-- Exclude the version being worked on (i.e. the one 
+                         that has a HEAD tag -->
+                    <j:if test="${!version.tag.equals('HEAD')}">
+                      <tr>
+                        <td>
+                          <a href="${maven.xdoc.distributionUrl}/${pom.artifactId}-${version}.${maven.xdoc.distributionType}">${pom.name} v${version}</a>
+                        </td>
+                      </tr>
+                    </j:if>
+                  </j:forEach>
+                </table>
+              </j:otherwise>
+            </j:choose>
+
+          </j:otherwise>
+        </j:choose>
+
+      </section>
+    </body>
+
+  </document>
+</project>

xdoc/src/plugin-resources/templates/downloads.xml

@@ -1,41 +0,0 @@
-<?xml version="1.0" encoding="$encoding" ?>
-<!-- 
-/*
- * 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.
- */
- -->
-
-<document>
-  
-  <!--
-   | Looks like for sanity we most likely must provide a distribution URL as
-   | the distributionSite and distributionDirectory don't map to anything
-   |   useful from the web.
-   -->
-  
-  <properties>
-    <title>Downloads</title>
-  </properties>
-
-  <body>
-    <section name="Downloads">
-      <p>
-        #set ($url = $escape.getText($project.distributionUrl))
-        <a href="$url">$url</a>
-      </p>
-    </section>
-  </body>
-</document>
-

xdoc/xdocs/changes.xml

@@ -22,9 +22,22 @@
   <properties>
     <title>Changes</title>
     <author email="dion@multitask.com.au">dIon Gillard</author>
+    <author email="vmassol@apache.org">Vincent Massol</author>
   </properties>
   <body>
     <release version="1.7-SNAPSHOT" date="in CVS">
+      <action dev="vmassol" type="add">
+        Added new download report along with a new link in the Maven
+        generated documentation. This new link will only appear if you have
+        defined the new <code>maven.xdoc.distributionUrl</code> property.
+        There is also a new <code>maven.xdoc.distributionType</code> property
+        that indicates what type of artifact your project is delivering. It
+        defaults to "jar".
+      <action dev="vmassol" type="add">
+        The xdoc plugin now supports generating custom reports using Jelly. 
+        It was previously only supporting Velocity. Simply name your report
+        templates with a ".jelly" extension.
+      </action>
       <action dev="brett" type="fix" issue="MPXDOC-98" due-to="fabrizio giustina">Allow reports to be generated even if they aren't linked from the "project reports" section by giving an empty link attribute to the register report tag.</action>
       <action dev="brett" type="fix" issue="MPXDOC-90" due-to="Corey Tripp">Only show "CVS Access Behind a Firewall" section if using CVS.</action>
       <action dev="brett" type="fix" issue="MPXDOC-96" due-to="fabrizio giustina">wrong lists generated for not expandable menu items. Some changes in patch were already put in place by brett.</action>

xdoc/xdocs/properties.xml

@@ -22,6 +22,7 @@
   <properties>
     <title>Xdoc Properties</title>
     <author email="smor@apache.org">Stéphane MOR</author>
+    <author email="vmassol@apache.org">Vincent Massol</author>
   </properties>
 
   <body>
@@ -498,6 +499,28 @@
             <code>file:</code> URL.
           </td>
         </tr>
+        <tr>
+          <td>maven.xdoc.distributionUrl</td>
+          <td>Yes</td>
+          <td>
+            Location where the artifacts are distributed. This property is 
+            optional. If it is not defined, then the Download report will 
+            not be added to the navigation menu. NOTE: In the future this 
+            information will be described in the POM. Usage example:
+            <code>maven.xdoc.distributionUrl=http://www.ibiblio.org/maven/maven/plugins</code>.
+          </td>
+        </tr>
+        <tr>
+          <td>maven.xdoc.distributionType</td>
+          <td>Yes</td>
+          <td>
+            Type of the distributed artifact. Override this property if
+            your project is distributing artifacts of a type different
+            that the default. NOTE: In the future 
+            this information will be described in the POM.
+            Default value: <code>maven.xdoc.distributionType=jar</code>
+          </td>
+        </tr>
       </table>
     </section>
   </body>