AntDoc: an Ant buildfile documentation generation - AntDocGUI: an Ant buildfile runner

AnDoc is an automatic Ant script documentation generation, in the same spirit as the must JavaDoc. This documentation enables to directly execute Ant build files. AntDoc is an Ant task.

AntDoc has now a GUI named AntDocGUI, which is a well featured Ant target runner.

The reason why

As Ant is becoming the open-source reference concerning process managment, as it is being used more and more in the developing world, I was pretty astonished that, at my knowledge, there is no tool at the moment that automatically generates Ant documentation from the script itself.

How many times did you have to type on a console this damned "ant -projecthelp" command in order to remember the exact name of an Ant script target? And once that you know the exact name of that target, is it not tedious to scroll up and down the targets it depends on? At last, when you know what target you want to execute, is is not sad that you have to open a shell or DOS console, in order to run the target?

When you work on a project where Ant scripts are used everywhere in order to manage the executables, some colleagues do not know how Ant works. Having some HTML documentation on the intranet may help those colleagues to make acquaintance with Ant: this is a typical use of AntDoc, and I think that in that special case, it may be very handy.

The motivation to create a new task comes from all those reasons. Hence, I decided to dedicate some time to the development of a tool that would do that stuff.

What it does

Generated HTML documentation

Target documentation

As I said, the basic purpose of this task is to provide automatic HTML documentation from Ant build files. The way the documentation is generated is totally inspired from JavaDoc: you will find an index, a summary, and you may switch from one project to another. As JavaDoc, AntDoc offers the opportunity to customize the visual rendering of the documentation through a Cascading Style Sheet (CSS) file, but also to use an HTML welcome page will be integrated to the generated documentation.

AntDoc relies on the XML build files in order to generate that documentation: it makes use of the project name, of each target dependencies and of each target description. This is the reason why you should strive to fill in as much as possible the description attributes of your Ant scripts if you want a smart documentation. By the way, target that are not documented within the XML will appear under a smaller font in the generated documentation. Hyperlinks are created for the Ant target dependencies, which helps you to navigate through the XML code.

Task documentation

But also, in order to help Ant beginners, and a reminder, AntDoc proposes to review all Ant tasks being used in the documentated Ant buildfiles: this should ease people at looking at examples on how to use Ant tasks. Everywhere a task name appears, it is marked-up so that you can directly browse the official documentation on Jakarta's web site .

Runtime from the documentation

It was so bad that you could not directly run your documented scripts from the HTML pages, that this could not last any longer. This is the reason why I am developing a little Graphical User Interface (GUI) that I called AntDocGUI, which behaves as a server. If you generate the AntDoc documentation with the runtime option, the generated HTML will embed a lightweight applet that behaves as a client. Within the documentation, you may click an icon related to the target that you want to execute, and the AntDocGUI will popup in the foreground, ready to execute your target.

AntDocGUI offers all basic features, such a tracing, and it is improving little by little.

A full GUI to execute Ant buildfiles

As AntDoc is growing, it now offers a modest GUI runtime environment. I know that the Jakarta project has launched a project named Antidote that should offer that kind of functionality, but Antidote is still not there... AntDocGUI, which is the name of the GUI may be an alternative to the Antidote tool.

I personaly use AntDocGUI at work and at home, and I spare much time.