JXR Ant Task

Version 2.1.0
Written by Matt Bertolini

License

The JXR Ant Task is licensed under the Apache License, Version 2.0.

Usage

Download the library from Maven Central and make sure it is available to ant in some way (e.g. On Ant's classpath or in a <path>).

Maven:

<dependency>
    <groupId>com.mattbertolini</groupId>
    <artifactId>jxr-ant</artifactId>
    <version>2.1.0</version>
</dependency>

Ivy:

<dependency org="com.mattbertolini" name="jxr-ant" rev="2.1.0"/>

In your ant file, load the task.

<taskdef resource="com/mattbertolini/jxr/ant/antlib.xml"/>

Parameters

Attribute	Description	Availability	Required
bottom	The text or HTML to place at the footer of the generated files.	all	No.
destdir	The destination directory where the generated files are saved.	all	Yes
doctitle	The document title to give the generated files.	all	No. Defaults to ${project.name} Xref Documentation
inputencoding	The character set to use when reading the input/source files.	all	No. Defaults to JVM file.encoding system property.
javadocdir	The directory where the equivalient javadoc files are located. Adding this attribute will link the javadoc with the xref files.	all	No
outputencoding	The character set to use when writing the generated files.	all	No. Defaults to JVM file.encoding system property.
sourcepath	The directory where the source files are located.	all	Yes unless a nested <sourcepath> is given.
stylesheet	The file path to the custom stylesheet to use when generating the documentation.	all	No
templatedir	The directory where the custom templates are located.	all	No
windowtitle	The window title to give the generated HTML files.	all	No. Defaults to ${project.name} Xref Documentation.

Parameters defined as nested elements

bottom

Same as the bottom attribute. Nested element allows for easier defining of large blocks of text or HTML.

doctitle

Same as the doctitle attribute.

Sourcepath

A Path. This element allows for multiple source paths to be combined and generated into the final generated documentation. All path elements must be directories. No individual files can be listed in the path. If defined, the sourcepath attribute is not needed.

windowtitle

The same as the window title attribute.

Examples

Here is a basic uasage example:

<jxr destdir="dest/docs/jxr" sourcepath="src"/>

Here is an example using the <sourcepath> nested element instead of the attribute:

<jxr destdir="dest/docs/jxr/">
    <sourcepath>
        <pathelement location="src"/>
    </sourcepath>
</jxr>

Here is an example with an HTML footer defined in the <bottom> nested element:

<jxr destdir="dest/docs/jxr" sourcepath="src">
    <bottom><![CDATA[<p>Footer text here</p>]]></bottom>
</jxr>

Here is an example with some classes excluded using a <patternset> element:

<jxr destdir="dest/docs/jxr" sourcepath="src">
    <patternset>
        <excludes name="**/example/subpackage/**"/>
    </patternset>
</jxr>

Gradle

Since Ant tasks are first-class citizens in Gradle, adding JXR-Ant to a gradle build is very easy. To start add the JXR-Ant dependency to the dependencies section. It is recommended you create a special configuration for the library:

configurations {
    jxr
}
dependencies {
    jxr group: 'com.mattbertolini', name: 'jxr-ant', version: '2.1.0'
}

Next, define the ant task an invoke it:

task runJxr() {
    ant.taskdef(resource: 'com/mattbertolini/jxr/ant/antlib.xml', classpath: configurations.jxr.asPath)
    ant.jxr(destDir: "$docsDir/jxr", sourcePath: files(sourceSets.main.java.srcDirs).asPath)
}

Here is a more complex example:

task runJxr(dependsOn: 'javadoc') {
    ant.taskdef(resource: 'com/mattbertolini/jxr/ant/antlib.xml', classpath: configurations.jxr.asPath)
    ant.jxr(destDir: "$docsDir/jxr", sourcePath: files(sourceSets.main.java.srcDirs).asPath, javadocDir: "$docsDir/javadoc") {
        bottom('<p>Footer text here</p>')
        patternset(excludes: '**/example/subpackage/**')
    }
}

Build and Test

Requirements

• Apache Ant - Version 1.8 or higher.
• JDK 6 or higher (Compiled with 1.6 source and target).

Build

To build this project, clone the repo and run the ant command:

$ git clone https://github.com/mattbertolini/JXR-Ant.git
$ cd JXR-Ant
$ ant

The distributable jar files will be located in the dist folder. The build reports (unit test, dependency, coverage, etc.) will be located in the build/reports dir.

To run the unit tests run the run-unit-tests task.

$ ant run-unit-tests

Bugs

If you find any bugs, please file them in the issue tracker above. Patches and pull requests are encouraged.

Release Notes

3.0.0.dev - In development. Not yet released.

• Minimum Java version now at 1.7.
• Updated build dependencies (JUnit, JaCoCo, Findbugs, etc).

2.1.0 - 2014-11-16

• Updating JXR dependency to 2.5. Backward compatible.

2.0.0 - 2013-12-20

• Updating JXR dependency to version 2.4.

1.0.0 - 2012-06-24

• Initial release.
• Uses JXR version 2.3