Skip to content

mattbertolini/JXR-Ant

Repository files navigation

JXR Ant Task

Version 2.1.0
Written by Matt Bertolini

Maven Central

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

About

An Ant task for the JXR report. Based on the JXR Maven plugin.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published