xml2doc Ant Wrapper - Generate Documentation from Ant

Contents

Return to main dbmstools documentation page.

Introduction

xml2doc-ant is a wrapper script to enable xml2doc to be executed as a task in Apache Ant. It works in tandem with the Jython Ant task provided with dbmstools, which provides much more functionality than that standard Ant script task.

See the xml2doc page for further details. You should also check the Use of DTD section on the XML schema page.

Prerequisites

As with all the Ant wrappers, this script uses Jython. See the installation page for details of the requirements to get any of the ant tasks working.

You must also taskdef the jython task somewhere in your build script (or in something it includes).

If you want to generate diagrams, you'll need dot from the graphviz package. Again, this is covered on the installation page.

Build Script

xml2doc-ant.py should be executed using the jython task mentioned above. It requires that the script attribute be set to dbmstoolsjar/filterdml-ant.py

<jython script="dbmstoolsjar/xml2doc-ant.py">

The script supports the following arguments:

Argument Example Details
xmlSchema ${db.scripts.dir}/ps.xml The path to the XML schema file. Mandatory
outputDir ${output.dir}/${ddl.scripts.dir} Directory where HTML output should be created. Mandatory
dbmsList postgres8, oracle CSV list of DBMS's for which to generate documentation. Mandatory, must contain at least one entry
baseName sampledb The base name to be used in generated file names. Optional, defaults to the database name in the XML schema
embedStyles N Should CSS styles be embedded in the HTML? Optional, defaults to 'N'. Doesn't apply if generating using frames
includeColumnDescriptions N Include descriptions for columns, keys etc? Optional, defaults to 'Y'
numIndexTableColumns 3 Number of columns in the table index at the top of the page. Optional, defaults to 4. Doesn't apply to frames
useFrames Y Should the documentation be generated as a frameset (style is similar to Javadoc)? Defaults to 'N', i.e. single page output
includeDiagrams Y Should schema diagrams be included? Optional, defaults to 'N'. Requires 'dot'
wikiMarkup Y Should Wiki markup in descriptions be interpreted? Optional, defaults to 'N'.
verbose Y If set, outputs extra output. Optional, defaults to 'N'

The script also supports a single mapargument called variables. The contents of this element are arguments whose names and values are the values you wish to pass to xml2ddl (for condition evaluation or token replacement). See the example below.

Example

A frame-based example, with diagrams, Wiki markup, and variables:

<jython script="dbmstoolsjar/xml2doc-ant.py">
    <argument name="xmlSchema" value="test/data/testSchema.xml"/>
    <argument name="outputDir" value="${output-dir}"/>
    <argument name="dbmsList" value="postgres8, mssql, hsql"/>
    <argument name="useFrames" value="Y"/>
    <argument name="includeDiagrams" value="Y"/>
    <argument name="wikiMarkup" value="Y"/>
    <mapargument name="variables">
        <argument name="aVariableName" value="aValue"/>
        <argument name="anotherVariableName" value="anotherValue"/>
    </mapargument>
</jython>