RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Visualizing Data: Self-Documenting Ant files : Page 4

Interactive graphical views of your Ant build files give you more information faster, reduce errors, and provide intuitive methods to help you comprehend, modify, and test build targets.

AntDoc API
Ant Pretty Build and Ant's projecthelp both present the essential API of your build file—the targets and their descriptions. Both provide an essentially static summary with no possibility for discerning any further details. If you have used Javadoc (or Ndoc or other similar tools that generate a documentation set from your source code) you will instantly appreciate the added capability of AntDoc. It creates a hyperlinked set of HTML documentation in the style of Javadoc.

AntDoc API

Ease of Installation2
  • Besides AntDoc.jar, need to download log4j.jar (which web site mentions) and xalan.jar (which web site does not mention).
  • Finding documentation on the setup for executing targets is difficult. Could not get targets to execute according to documentation.
Ease of Use4Buttons to execute targets will not work without additional setup, though there is no indication of this in the GUI.
Shows Targets5
  • Hyperlinked list of targets; each target displays with description, hyperlinked dependencies, source, and hyperlinked Ant tasks.
  • Does not differentiate public from private targets.
Shows Connections4Dependencies are hyperlinked.
  • Hyperlinked dependencies.
  • Hyperlinked API for base Ant tasks.
  • Does not differentiate public from private targets.
  • Execution did not work for me.
Sample file build-antdoc.xml
Download AntDoc, Xalan
CLASSPATH setting ./customJar/AntDoc.jar;./customJar/log4j-1.2.8.jar;./customJar/xalan.jar

AntDoc renders an excellent presentation of your build file, but it does require some setup. You will need the AntDoc.jar and log4j.jar files available on the AntDoc site, as well as the xalan.jar and serializer.jar files available from Apache's Xalan site (and AntDoc does not even mention these as requirements). You must put serializer.jar in the same directory as xalan.jar, but the location does not need to be referenced in your CLASSPATH. Speaking of CLASSPATH, you need to set the CLASSPATH externally rather than use the classpath attribute of the <taskdef> element. (It should execute just as well either way, but I could not get it to work without explicitly defining the CLASSPATH.)

After setting up AntDoc, you can generate AntDoc documentation for your build by just defining and executing an <AntDoc> task within Ant itself, as shown in the sample code below:

   <?xml version="1.0"?>
   <?xml-stylesheet type="text/xsl" href="include/antprettybuild-core-2.2.0.xsl"?>
   <project name="MyProject" default="antdoc.html" basedir=".">
       <description>simple example build file</description>
       <property name="docPath" location="doc"/>
       <property name="customJarPath" location="./customJar"/>
       <target name="build" depends="antdoc.html, showCompleted"/>
       <target name="showCompleted">
               <echo>Build complete</echo>
       <target name="antdoc.html"
           depends="antdoc.checkIfRequired" unless="antdocBuild.notRequired"
           description="build API documentation for build file" >
           <taskdef name="AntDoc" classname="org.ed.pack.ant.AntDoc" />
           <AntDoc destination="${docPath}/antdocAPI"
                   runtime="yes" hide="yes">
               <title>Ant Demo Documentation</title>
               <header>Ant Demo Documentation</header>
               <fileset file="${ant.file}"/>
           <echo>antdoc complete.</echo>
       <!-- <internal target> -->
       <target name="antdoc.checkIfRequired">
           <uptodate property="antdocBuild.notRequired"
               <srcfiles file="${ant.file}"/>
       <target name="help" description="a wee bit of help">
           <java classname="org.apache.tools.ant.Main">
               <arg value="-buildfile"/>
               <arg value="${ant.file}"/>
               <arg value="-projecthelp"/>
       <target name="antDocGUI">
           <java fork="true" jar="${customJarPath}/AntDoc.jar">
               <arg value='-Dant.home="%ANT_HOME%"'/>
               <arg value="org.ed.pack.ant.AntDocGUI"/>
Figure 8. An AntDoc Build: The first invocation shows the output from a typical execution; later invocations skip the build if the build file has not changed since the last execution.
The preceding code contains an added dependent clause to make the build conditional; AntDoc will execute only if the build file has changed since the last time you ran it. Figure 8 shows the results of a typical AntDoc execution—twice, so that you can see it skip the build the second time around (the red numbers indicate the two runs).

So what does AntDoc actually deliver? Quite a lot. Figure 9 shows the home page of the generated application set for the sample build file. The page has the standard three-pane layout of Javadoc, with projects in the upper left, targets in the lower left, and the current project or target in the main, right-hand pane. As you click on items in the navigation panes, the main pane changes to show the selected item.

Figure 9. An AntDoc Result: The home page resembles Javadoc-generated documentation, with navigation controls on the left and the current item details shown on the right.

The following brief walkthrough should serve to show you how powerful AntDoc's visualization of your build files can be.

First, click on a simple target, the help target (see Figure 10). The main pane renders this selected target in three sections: the name, the description, and the source code.

Figure 10. Simple Target: Selecting a target such as the "help" target from the "All Targets" pane shows the details of that target in the main pane, including the name, the description, and the source code.
Figure 11. Compound Target: Selecting a compound target such as "build" adds hyperlinked references to the connected elements.
But wait; it gets better! Now select a more complicated target, the build target. As shown in Figure 11, you can see that the top section of the main pane shows not only the name of the target, but also its hierarchy. (The help target in Figure 10 had no connected tasks, so it just displayed the name.) Each of the connected targets is a hyperlink—both in the top hierarchy section and in the bottom source code section—so you can click any link to jump to the documentation for that element.

If, for example, you click either of the antdoc.html links from Figure 11, you will jump to that documentation page (see Figure 12). Note that the hierarchy at the top is now relative to the newly displayed target. So you may "drill down" via hyperlinks to each connected task. Figure 12 adds one more feature to the display. Notice the hyperlink on the echo task near the bottom of the Detail section.

Figure 12. Drill-Down Capability: The relative hierarchy in the top portion of the display lets you drill down to other connected targets.
Figure 13. Linked Tasks: Clicking a linked task displays the standard Ant documentation for that task.

Figure 14. Usage Page: The Usage page summarizes and provides hyperlinks to the tasks used for each target.
AntDoc not only connects your targets together in a hyperlinked web, it also connects your build file to the Ant documentation set for all standard Ant tasks. Clicking on the echo link, therefore, opens the documentation for the echo task itself (see Figure 13).

Next, scroll to the top of any page in the documentation set and you will see some standard links (see Figure 14). Clicking the Usage link displays a summary of standard Ant tasks that you have used, and which targets they are used in. Again, all of these are hyperlinked so you may jump between your targets and Ant's tasks.

Finally, access the project page by clicking the project name in the upper-left navigation pane (see Figure 15). This page lists the targets in the rightmost column, labeled curiously as "Description." The description column actually includes both the name and the description of each target. The Depends and Runtime columns present essentially identical information, the former in a tree format, and the latter in a linear sequence.

Figure 15. Project Page: The project page summarizes the targets in your build, along with their descriptions and dependents.
AntDoc lets you execute Ant targets in a manner similar to Ant Pretty Build; however, that's not where AntDoc shines. You need to perform some setup before you can press any of those buttons you can see in the Run column in Figure 15. It's not obvious where to find the documentation for the run-time setup, so here's the link: http://antdoc.free.fr/AntDoc_documentation_content.php. In a nutshell, you need to launch a separate application—the AntDocGUI—then connect to that application on the project page (see Figure 15), and only then may you execute your selected target. That's fine in theory but in practice it requires some fiddling with the configuration. Also, the batch file provided to launch AntDocGUI for Windows failed because my Ant installation was in the standard "Program Files" location, and the batch file is missing quotes around the path, so the space in the name caused a problem. In the end, I was not able to get the AntDocGUI program to run. However, given the excellent quality of the rest of AntDoc, I am certain that AntDocGUI would run quite well if its documentation was able to get this humble developer through the appropriate hoops.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date