This tool is not an open-source project so far. However, this does not involve that it is not free of use. At the opposite, feel free to use it and spread it as is.
One reason why the tool is not part of an open-source project is that I would not have time enough to dedicate to the administration.
This task is still under development, which means that it is subject to change. However, the task works under certain circumstances that are described in this paragraph.
This task has only been tested under Windows NT V4.0 SP6 and under Windows 2000 SP1. Please, send feedback to notify whether the use of this task was OK under other platforms and configurations!
The exact configuration under which the task has been successfully tested is the following:
welcome" attribute, Xalan is required because Saxon seems to be bugged with the CDATA sections...A lot of bugs make the project still in beta version. In order to spare some time to the end-user, here are some known bugs, as well as their workaround.
When "$" (dollar symbol) is being used, it means that the appended variable should be considered as an environment variable: $ANT_HOME is to be translated as %ANT_HOME% under Windows and as ${ANT_HOME} under UNIX.
In this section and for the remaining of the page, it assumed that you are familiar with the open-source Jakarta's Ant tool.
In general, when an extra jar is needed it order to make the task work, it means that you should put that jar in the $ANT_HOME/lib directory.
At the moment, in order to use this task, you need to have Saxon XSLT Processor installed (at least its main jar saxon.jar), and to have it copied in the $ANT_HOME/lib directory, where $ANT_HOME stands for the Ant distribution folder. You also need Xerces Java 1 to be installed. Off course, it is also required to place the provided AntDoc Ant task AntDoc.jar byte-code archive file in that same directory.
The aim of this task is to provide a tool that automatically generates HTML documentation from Ant build files. The way this documentation is generated is similar to the Javadoc tool. With the latest version, you may now execute your Ant scripts from the generated documentation: the execution is performed in a GUI called AntDoc GUI.
In order to take a full benefit of AntDoc, you should comment and describe your Ant builfile project and targets as much as possible. Ant provides the ability to deliver description through the description inner element within the project top XML element: you can place some HTML tags in here, provided you use entity references ("<" has to be replaced by "<") and AntDoc will translate thei description properly. However, this is not very elegant and this is the reason why you had better create an XML comment ("<-- My comment -->") before this description element: AntDoc will interprete it as well, and this XML comment is a safe place where to insert HTML tags.
This is exactly the same picture for the description attribute of the target element: AntDoc leaves you the ability to stuff this attribute with HTML tags provided that you use XML entity references. However, the XML comment before you Ant target is a better practice.
Within the AntDoc task, you should specify through the standard fileset element the Ant buildfiles that should be documented. Each matched Ant buildfile will be documented unless the top level project element has a name attribute.
At the moment, it is not possible to set the header, title and footer text as plain HTML; if you provide HTML, it will not be output correctly, but you will see the un-interpreted markup.The HTML markup will now be properly output. Just beware of the "title" element, which will be also used in order to provide a title to the HTML file: if you use HTML markups, they will be displayed as text in that title!
The main page is named index.html and it should be first opened when browsing the documentation. This HTML file encompasses two framesets:
The generated documentation also includes a CSS stylesheet named stylesheet.css, which you may customize at your will. Warning: each time that you re-generate the documentation, this stylesheet will be overwritten! You may now specify the stylesheet that you want AntDoc to use.
Note that the task generates temporary files and then deletes them.
| Attribute | Description | Type | Default | Required |
| destination | The directory under which the HTML documentation is generated. If the directory does not exist and that it can be created, it is created. | path | ".", that is to say the current directory. |
no |
| buildfile | The Ant buildfile which should be documented. If the attribute is set, the inner <fileset> are discarded |
path | null for the moment (in the future ${ant.file}, that is to say the current Ant buildfile) |
no |
| processor | The fully qauified class name of the javax.xml.transform.TransformerFactory interface implementation to be used as an XSL transformer factory. Enables to specify what exact implementation of XSLT should be used. Depending on that implementation, a specific XSL will be used. Possible values are:
|
string | the class name of the first implementation of javax.xml.transform.TransformerFactory encountered in the classpath |
no |
| welcome | Enables to specify an HTML welcome page, which will be displayed on the index.html first frameset. This HTML file must contain a body element, which will be plainly copied. In order to make that feature work, you need to have Xalan Java V2.X xalan.jar library in your $ANT_HOME/lib |
path | the default AntDoc welcome page will be generated. | no |
| css | Enables to specify what Cascasding Style Sheet (CSS) file should be used. The provided CSS will be copied to the destination directory, and name stylesheet.css; it looks like the traditional Javadoc stylesheet. |
path | the default AntDoc stylesheet, which has the same format that the Javadoc's. | no |
| hide | All Ant target with no explicit description ("description" attribute missing or empty) will not be documented, even if explicetly included by the filtering mechanism. This option has the priority over the filtering mechanism (see the "filter" inner element) | boolean | no | no |
| antURL | The URL of Ant official web site; or the local URL of your Ant documentation installation directory ($ANT_HOME/docs environment variable, ${ant.home}/docs Ant property). This URL will be used so as to generate documentation that enables to link a task use to its documentation.In the case when you specify a local URL, do not forget to prepend the path with " file:/" (see example). |
path | http://jakarta.apache.org/ant, the current Ant web site. |
no |
| runtime | Indicates to AntDoc whether it should incorporate within the generated HTML pages, the necessary resources in order to be able to execute the targets from your browser. If it is enabled, some extra icons will be generated close to each documented target, and when clicking an icon, the target will be ready to be executed in the AntDoc GUI if available. Moreover, some input parameters will be displayed at the top of the HTML, in order to specify on what host and what port number the AntDoc GUI listens. Do not forget to set ANT_HOME environment variable in that case, if |
boolean | no | no |
| local | Indicates to AntDoc whether the generated HTML pages should use the local applet jar, or the one on the AntDoc "official" site. This attribute is only taken into account if |
boolean | no | no |
| gui | If enabled, launches the AntDoc GUI: documentation generated is discarded in that case. This GUI enables to run Ant targets selected in the HTML AntDoc. | boolean | no | no |
| port | Only used if gui is enabled. Specifies on which port number the AntDoc GUI should listen to incoming requests from the HTML generated AntDoc. |
integer | 111 | no |
<![CDATA[]]> data section.
<![CDATA[]]> data section.
buildfile attribute is not defined! This nested element is an Ant FileSet, which enables to define all the Ant build files which are bound to be documented. Each reachable file through this Ant FileSet will be considered as a Ant build file and will be documented.
fileset nested elements may be used. When using that element, you must have the jar of Jakarta RegExp present in $ANT_HOME/lib!
This element enables to filter the Ant target that are bound to be documented. The element itself is composed by exclude and include which are empty elements with a mandatory name attribute that should represent a regular expression. This regular expression must comply Regexp patterns, otherwise it is ignored.
Note that when this element is missing, no filtering is applied.
Now, when you wish not to generate documentation for all the Ant targets, you may create a filter element within the AntDoc element, and within that filter, create include and exclude elements with a name attribute equal to a regular expression that will be matched against each target element name attribute. If the overall filtering excludes the target, the target documentation will not be generated. As a consequence, and this is a temporary bug, the hyperlinks that point to it are incorrect!
When the set of filters both explicitely includes and excludes a given target, the Ant default directory-based policy applies:
You may easily transpose that rule to the AntDoc filtering mechanism.Ant gives you two ways to create a subset, both of which can be used at the same time:
- Only include files/directories that match at least one pattern of a set of patterns.
- Exclude files/directories that match at least one pattern a set of patterns.
When both inclusion and exclusion are used, only files/directories that match the include patterns, and don't match the exclude patterns, are used.
<taskdef
name="AntDoc"
classname="org.ed.pack.ant.AntDoc"
/>
<AntDoc
destination="antdoc"
buildfile="${ant.file}"
/>
This example generates the AntDoc for the current Ant buildfile. Note that no runtime is embedded to the generated HTML pages.
<taskdef
name="AntDoc"
classname="org.ed.pack.ant.AntDoc"
/>
<AntDoc
destination="antdoc"
antURL="file:/${ant.home}/docs"
>
<filter>
<include name="^antdoc."/>
<include name="^usage"/>
<include name="dummy"/>
<exclude name="antdoc.test.out"/>
</filter>
<title>My Title</title>
<header>My Header</header>
<footer>My Footer</footer>
<fileset dir="..">
<include name="build.xml"/>
<exclude name="*_build.xml"/>
</fileset>
</AntDoc>
This example shows that the optional AntDoc should be "loaded dynamically" within the Ant build file script. But you do not have to put the AntDoc.jar file into the $ANT_HOME/lib directory, and instead, you may use the taskdef classpath attribute.