Author: niallp Date: Mon Feb 4 08:55:12 2008 New Revision: 618323 URL: http://svn.apache.org/viewvc?rev=618323&view=rev Log: Update the site/docs for recent changes
Added: commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml (with props) commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml (with props) Removed: commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-mojo.xml Modified: commons/sandbox/commons-build-plugin/src/site/site.xml commons/sandbox/commons-build-plugin/src/site/xdoc/development.xml commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-build.xml commons/sandbox/commons-build-plugin/src/site/xdoc/index.xml Modified: commons/sandbox/commons-build-plugin/src/site/site.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/site.xml?rev=618323&r1=618322&r2=618323&view=diff ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/site.xml (original) +++ commons/sandbox/commons-build-plugin/src/site/site.xml Mon Feb 4 08:55:12 2008 @@ -25,7 +25,10 @@ <menu name="Build Plugin"> <item name="Overview" href="/index.html"/> <item name="Goals"> - <item name="generate-xdocs" href="/generate-xdocs-build.html"/> + <item name="Generate XDOCS" href="/generate-xdocs-build.html"> + <item name="jira-page" href="/generate-xdocs-build.html#commons:jira-page"/> + <item name="download-page" href="/generate-xdocs-build.html#commons:download-page"/> + </item> <item name="copy-javadoc-files" href="/copy-javadoc-files-build.html"/> </item> <item name="Help" href="/development.html"> Modified: commons/sandbox/commons-build-plugin/src/site/xdoc/development.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/xdoc/development.xml?rev=618323&r1=618322&r2=618323&view=diff ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/xdoc/development.xml (original) +++ commons/sandbox/commons-build-plugin/src/site/xdoc/development.xml Mon Feb 4 08:55:12 2008 @@ -91,14 +91,6 @@ for these in the associated <i>mapping document</i>. </p> - <p> - At the moment each <i>goal</i> has been defined in a separate ant build script - and the - maven <b><i>goal</i></b>, <b><i>ant script file</i></b> name and ant <b><i>target</i></b> - have all been named the same. This is not a maven ant plugin requirement, but just a convention - in this plugin to make it easier to find the ant <i>script file</i> and <i>target</i> associated - with a maven <i>goal</i> - </p> - </section> <section name="Debugging"> @@ -107,7 +99,7 @@ The <i>message level</i> for ant is <i>info</i> by default. Running the plugin goal using a message level of <i>debug</i> can help in discovering problems - for example: <source><![CDATA[ - mvn commons:generate-xdocs -DantMessageLevel=debug + mvn commons:jira-page -DantMessageLevel=debug ]]></source> </p> Added: commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml?rev=618323&view=auto ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml (added) +++ commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml Mon Feb 4 08:55:12 2008 @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<!-- + $HeadURL$ + $Revision$ $Date$ + --> +<document> + <properties> + <title>commons-build-plugin - commons:download-page</title> + </properties> + <body> + <section name="commons:download-page"> + <p>Commons Build Ant Mojo: Generate Download page</p> + <p><b>Mojo Attributes</b>:<ul> + <li>Requires a Maven 2.0 project to execute.</li> + <li>Is NOT inherited by default in multi-project builds.</li> + </ul> + </p> + <subsection name="Required Parameters"> + <table> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><b><a href="#commons.release.version">commons.release.version</a></b></td> + <td><code>String</code></td> + <td>The version of the latest release of the project. Default value is <code>${commons.release.version}</code>.</td> + </tr> + <tr> + <td><b><a href="#commons.release.name">commons.release.name</a></b></td> + <td><code>String</code></td> + <td>The final name (i.e. artifactId-version) of the artifacts being built. Default value is <code>${project.artifactId}-${commons.release.version}</code>.</td> + </tr> + <tr> + <td><b><a href="#commons.binary.suffix">commons.binary.suffix</a></b></td> + <td><code>String</code></td> + <td>The suffix for the binary distro. Default value is <code>${commons.binary.suffix}</code>.</td> + </tr> + <tr> + <td><b><a href="#basedir">basedir</a></b></td> + <td><code>File</code></td> + <td>The base directory from which to execute the Ant script. Default value is <code>${basedir}</code>.</td> + </tr> + </table> + </subsection> + <subsection name="Optional Parameters"> + <table> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><b><a href="#messageLevel">messageLevel</a></b></td> + <td><code>String</code></td> + <td>The message-level used to tune the verbosity of Ant logging. Default value is <code>info</code>.</td> + </tr> + </table> + </subsection> + <subsection name="Parameter Details"> + <p><b><a name="commons.release.version">commons.release.version</a></b></p> + <p>The version of the latest release of the project.</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Default</b>: <code>${commons.release.version}</code></li> + </ul><hr/><p><b><a name="commons.release.name">commons.release.name</a></b></p> + <p>The final name (i.e. artifactId-version) of the artifacts being built.</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Default</b>: <code>${project.artifactId}-${commons.release.version}</code></li> + </ul><hr/><p><b><a name="commons.binary.suffix">commons.binary.suffix</a></b></p> + <p>The suffix for the binary distro.</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Default</b>: <code>${commons.binary.suffix}</code></li> + </ul><hr/><p><b><a name="basedir">basedir</a></b></p> + <p>The base directory from which to execute the Ant script.</p> + <ul> + <li><b>Type</b>: <code>java.io.File</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Expression</b>: <code>${antBasedir}</code></li> + <li><b>Default</b>: <code>${basedir}</code></li> + </ul><hr/><p><b><a name="messageLevel">messageLevel</a></b></p> + <p>The message-level used to tune the verbosity of Ant logging.</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>No</code></li> + <li><b>Expression</b>: <code>${antMessageLevel}</code></li> + <li><b>Default</b>: <code>info</code></li> + </ul> + </subsection> + </section> + </body> + </document> \ No newline at end of file Propchange: commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml ------------------------------------------------------------------------------ svn:eol-style = native Propchange: commons/sandbox/commons-build-plugin/src/site/xdoc/download-page-mojo.xml ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL Modified: commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-build.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-build.xml?rev=618323&r1=618322&r2=618323&view=diff ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-build.xml (original) +++ commons/sandbox/commons-build-plugin/src/site/xdoc/generate-xdocs-build.xml Mon Feb 4 08:55:12 2008 @@ -28,94 +28,130 @@ <body> + <section name="Generating XDOC files"> + <p> + The <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.build.xml"> + generate-xdocs.build.xml</a> Ant build script contains targets for the following goals: + <ul> + <li><a href="#commons:jira-page">commons:jira-page</a> - Generate a JIRA Issue Tracking page for a component</li> + <li><a href="#commons:download-page">commons:download-page</a> - Generate a Download page for a component's latest release</li> + </ul> + </p> <p> - This <i>mojo</i> (or <i>ant build script</i>) currently generates - the followng custom xdoc pages for Commons components (using + This script generates custom xdoc pages for Commons components using <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/">templates</a> and <a href="http://ant.apache.org/manual/CoreTasks/filter.html">Ant's filtering</a> functionality: </p> - <ul> - <li><a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/issue-tracking-template.xml">issue-tracking-template.xml</a> - template used to generate custom issue tracking page</li> - <li><a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/dowload-page-template.xml">dowload-page-template.xml</a> - template used to generate custom issue download page (<b>download_</b><i>component</i><b>.xml</b>)</li> - </ul> <p> - See: + These goals (re-)generate xdoc files in either the default m1 location (i.e. <code>xdocs</code>) or the default m2 location + (i.e. <code>src/site/xdoc</code>). Once generated these can be checked into svn and the component's site regenerated using <code>mvn site</code>. </p> - <ul> - <li><a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a> - Ant build script</li> - <li><a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> - mapping document</li> - <li><a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/">src/main/resources/commons-xdoc-templates</a> - xdoc template files directory</li> - <li><a href="generate-xdocs-mojo.html">Parameters</a></li> - </ul> </section> - <section name="Configuring"> - <p> - Each component's <code>pom.xml</code> needs the following <i>properties</i> configured: - <ul> - <li><b>commonsComponentId</b> - Commons component id</li> - <li><b>commonsReleaseVersion</b> - The version number of the latest release of the component</li> - <li><b>commonsXdocsDir</b> - The component's xdoc directory (defaults to "xdocs")</li> - <li><b>commonsJiraId</b> - JIRA's external (upper case) id for the component</li> - <li><b>commonsJiraPid</b> - JIRA's internal (numeric) id for the component</li> - <li><b>commonsComponentId</b> - Commons component id</li> - </ul> - </p> + <section name="commons:jira-page" href="jira-page"> - <p>For example for Commons Chain: + <subsection name="Overview"> + <p> + The <code>commons:jira-page</code> goal generates a custom JIRA Issue Tracking page for a component. + Execute the goal using the following command: <source>mvn commons:jira-page</source> + </p> + + <p> + <strong>Note:</strong> The Issue tracking page should only need to be generated initially + for a component or if the issue tracking template changes. + </p> + + <p> + This goal uses the following: + <ul> + <li>The goal is mapped to the ant script/target using the <code>jira-page</code> mojo defintion in the + <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li> + <li>Executes the <code>jira-page</code> target in + <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a> + ant script</li> + <li>Uses the <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/issue-tracking-template.xml">issue-tracking-template.xml</a> + template</li> + <li>Uses the <a href="jira-page-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li> + </ul> + </p> + </subsection> + + <subsection name="Configuration"> + <p> + To generate a JIRA page, the following <i>properties</i> are configured in the component's <code>pom.xml</code> + <ul> + <li><b>commons.jira.id</b> - JIRA's external (upper case) id for the component</li> + <li><b>commons.jira.pid</b> - JIRA's internal (numeric) id for the component</li> + </ul> + </p> + <p> + Example configuration for Commons Chain: <source><![CDATA[ <properties> - <commonsComponentId>chain</commonsComponentId> - <commonsReleaseVersion>1.1</commonsReleaseVersion> - <commonsXdocsDir>xdocs</commonsXdocsDir> - <commonsJiraPid>12310462</commonsJiraPid> - <commonsJiraId>CHAIN</commonsJiraId> + <commons.jira.id>CHAIN</commons.jira.id> + <commons.jira.pid>12310462</commons.jira.pid> </properties> ]]></source> - </p> + </p> + </subsection> - <p> - <strong>N.B.</strong> The reason for using <i><properties></i> rather than the plugin's - <i><configuration></i> element is that hopefully the plugin will be configured in the - commons-parent pom.xml - which will mean that each component won't have to add the plugin to - their build section. - </p> + </section> - <p> - In the meantime to try this out then configure the plugin in the component's pomx.xml - as follows: + + <section name="commons:download-page" href="download-page"> + + <subsection name="Overview"> + <p> + The <code>commons:download-page</code> goal generates a custom Download page for the latest release of a component. + Execute the goal using the following command: <source>mvn commons:download-page</source> + </p> + + <p> + <strong>Note:</strong> The Download page should only need to be re-generated after a new release of the component + or if the download page template changes. + </p> + + <p> + This goal uses the following: + <ul> + <li>The goal is mapped to the ant script/target using the <code>download-page</code> mojo defintion in the + <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li> + <li>Executes the <code>download-page</code> target in + <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a> + ant script</li> + <li>Uses the <a href="http://svn.apache.org/repos/asf/commons/sandbox/commons-build-plugin/src/main/resources/commons-xdoc-templates/download-page-template.xml">download-page-template.xml</a> + template</li> + <li>Uses the <a href="download-page-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li> + </ul> + </p> + </subsection> + + <subsection name="Configuration"> + <p> + To generate a Download page, the following <i>properties</i> are configured in the component's <code>pom.xml</code> + <ul> + <li><b>commons.componentid</b> - Commons component id</li> + <li><b>commons.release.version</b> - The version number of the latest release of the component</li> + <li><b>commons.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the binary release + (some components use "-bin", others have no suffix)</li> + </ul> + </p> + <p> + Example configuration for Commons Chain: <source><![CDATA[ - <build> - <plugins> - <plugin> - <groupId>org.apache.commons</groupId> - <artifactId>commons-build-plugin</artifactId> - <version>1.0-SNAPSHOT</version> - <executions> - <execution> - <phase>pre-site</phase> - <goals> - <goal>generate-xdocs</goal> - </goals> - </execution> - </executions> - </plugin> - </plugins> - </build> + <properties> + <commons.componentid>chain</commons.componentid> + <commons.release.version>1.1</commons.release.version> + <commons.binary.suffix></commons.binary.suffix> + </properties> ]]></source> - </p> - - <p> - Running <code>mvn site</code> should cause the pages to be generated. Alternatively to just - generate the pages use <code>mvn commons:generate-xdocs</code>. The pages are output to - the site's xdocs directory (should we check these in to svn?) and will be generated into - html pages by the maven site creation process. - </p> + </p> + </subsection> </section> Modified: commons/sandbox/commons-build-plugin/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/xdoc/index.xml?rev=618323&r1=618322&r2=618323&view=diff ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/xdoc/index.xml (original) +++ commons/sandbox/commons-build-plugin/src/site/xdoc/index.xml Mon Feb 4 08:55:12 2008 @@ -44,10 +44,26 @@ <p> Available Goals: <ul> - <li><a href="generate-xdocs-build.html">commons:generate-xdocs</a> - Generate Standard Commons xdoc files</li> + <li><a href="generate-xdocs-build.html#commons:jira-page">commons:jira-page</a> - Generate a custom JIRA Issue Tracking page for a component</li> + <li><a href="generate-xdocs-build.html#commons:download-page">commons:download-page</a> - Generate a Download page for the component's latest release</li> <li><a href="copy-javadoc-files-build.html">commons:copy-javadoc-files</a> - Copy NOTICE and LICENSE files to -javadoc jar</li> - </ul> + </p> + </section> + + <section name="Trying out the plugin"> + <p> + Configure the plugin in the <code>build</code> section of the <code>pom.xml</code> +<source><![CDATA[ + <plugin> + <groupId>org.apache.commons</groupId> + <artifactId>commons-build-plugin</artifactId> + <version>1.0-SNAPSHOT</version> + </plugin> +]]></source> + </p> + <p> + Configure any properties required by the goal and try exectuing. </p> </section> Added: commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml URL: http://svn.apache.org/viewvc/commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml?rev=618323&view=auto ============================================================================== --- commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml (added) +++ commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml Mon Feb 4 08:55:12 2008 @@ -0,0 +1,103 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<!-- + $HeadURL$ + $Revision$ $Date$ + --> +<document> + <properties> + <title>commons-build-plugin - commons:jira-page</title> + </properties> + <body> + <section name="commons:jira-page"> + <p>Commons Build Ant Mojo: Generate Issue Tracking page</p> + <p><b>Mojo Attributes</b>:<ul> + <li>Requires a Maven 2.0 project to execute.</li> + <li>Is NOT inherited by default in multi-project builds.</li> + </ul> + </p> + <subsection name="Required Parameters"> + <table> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><b><a href="#commons.jira.id">commons.jira.id</a></b></td> + <td><code>String</code></td> + <td>The external JIRA id for the project (alphabetic, upper case) Default value is <code>${commons.jira.id}</code>.</td> + </tr> + <tr> + <td><b><a href="#commons.jira.pid">commons.jira.pid</a></b></td> + <td><code>String</code></td> + <td>The internal JIRA id for the project (numeric) Default value is <code>${commons.jira.pid}</code>.</td> + </tr> + <tr> + <td><b><a href="#basedir">basedir</a></b></td> + <td><code>File</code></td> + <td>The base directory from which to execute the Ant script. Default value is <code>${basedir}</code>.</td> + </tr> + </table> + </subsection> + <subsection name="Optional Parameters"> + <table> + <tr> + <th>Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td><b><a href="#messageLevel">messageLevel</a></b></td> + <td><code>String</code></td> + <td>The message-level used to tune the verbosity of Ant logging. Default value is <code>info</code>.</td> + </tr> + </table> + </subsection> + <subsection name="Parameter Details"> + <p><b><a name="commons.jira.id">commons.jira.id</a></b></p> + <p>The external JIRA id for the project (alphabetic, upper case)</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Default</b>: <code>${commons.jira.id}</code></li> + </ul><hr/><p><b><a name="commons.jira.pid">commons.jira.pid</a></b></p> + <p>The internal JIRA id for the project (numeric)</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Default</b>: <code>${commons.jira.pid}</code></li> + </ul><hr/><p><b><a name="basedir">basedir</a></b></p> + <p>The base directory from which to execute the Ant script.</p> + <ul> + <li><b>Type</b>: <code>java.io.File</code></li> + <li><b>Required</b>: <code>Yes</code></li> + <li><b>Expression</b>: <code>${antBasedir}</code></li> + <li><b>Default</b>: <code>${basedir}</code></li> + </ul><hr/><p><b><a name="messageLevel">messageLevel</a></b></p> + <p>The message-level used to tune the verbosity of Ant logging.</p> + <ul> + <li><b>Type</b>: <code>java.lang.String</code></li> + <li><b>Required</b>: <code>No</code></li> + <li><b>Expression</b>: <code>${antMessageLevel}</code></li> + <li><b>Default</b>: <code>info</code></li> + </ul> + </subsection> + </section> + </body> + </document> \ No newline at end of file Propchange: commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml ------------------------------------------------------------------------------ svn:eol-style = native Propchange: commons/sandbox/commons-build-plugin/src/site/xdoc/jira-page-mojo.xml ------------------------------------------------------------------------------ svn:keywords = Date Author Id Revision HeadURL