tessl/maven-org-codehaus-groovy--groovy-ant

Apache Groovy Ant Task integration library providing seamless integration between Groovy scripting capabilities and Apache Ant build automation framework

—

Pending

Overview

Eval results

Files

Documentation Generation

Name: tessl/maven-org-codehaus-groovy--groovy-ant
Author: tessl

The Groovydoc Ant task generates comprehensive API documentation from Groovy and Java source files, providing customizable HTML output with support for templates, stylesheets, and cross-referencing.

Capabilities

Groovydoc Task

Generates HTML documentation from Groovy source files with extensive customization options and template support.

/**
 * Access to the GroovyDoc tool from Ant for generating API documentation
 * from Groovy and Java source files.
 */
public class Groovydoc extends org.apache.tools.ant.Task {
    /** Set source directories to find source files */
    public void setSourcepath(Path src);
    
    /** Set directory where GroovyDoc output will be generated */
    public void setDestdir(File dir);
    
    /** Control whether author information is displayed */
    public void setAuthor(boolean author);
    
    /** Control whether hidden timestamp appears in generated HTML */
    public void setNoTimestamp(boolean noTimestamp);
    
    /** Control whether hidden version stamp appears in generated HTML */
    public void setNoVersionStamp(boolean noVersionStamp);
    
    /** Control whether scripts are processed for documentation */
    public void setProcessScripts(boolean processScripts);
    
    /** Control whether 'main' method is displayed for scripts */
    public void setIncludeMainForScripts(boolean includeMainForScripts);
    
    /** Set filename extensions to process (colon-separated list) */
    public void setExtensions(String extensions);
    
    /** Set package names to process (comma-separated, may use wildcards) */
    public void setPackagenames(String packages);
    
    /** Compatibility method for external file usage (ignored) */
    public void setUse(boolean b);
    
    /** Set title for HTML <title> tag */
    public void setWindowtitle(String title);
    
    /** Set title for overview page */
    public void setDoctitle(String htmlTitle);
    
    /** Set overview file to include in generated documentation */
    public void setOverview(File file);
    
    /** Set access level scope (public, protected, package, private) */
    public void setAccess(String access);
    
    /** Include all classes and members (private scope) */
    public void setPrivate(boolean b);
    
    /** Include only public classes and members */
    public void setPublic(boolean b);
    
    /** Include protected and public classes and members */
    public void setProtected(boolean b);
    
    /** Include package, protected and public classes and members */
    public void setPackage(boolean b);
    
    /** Set footer text for each generated page */
    public void setFooter(String footer);
    
    /** Set header text for each generated page */
    public void setHeader(String header);
    
    /** Set character encoding for generated files */
    public void setCharset(String charset);
    
    /** Set file encoding for writing generated files */
    public void setFileEncoding(String fileEncoding);
    
    /** Set custom CSS stylesheet file */
    public void setStyleSheetFile(File styleSheetFile);
    
    /** Create external documentation link */
    public LinkArgument createLink();
    
    /** Execute documentation generation */
    public void execute() throws BuildException;
    
    /** Get package templates (overridable for custom implementations) */
    protected String[] getPackageTemplates();
    
    /** Get document templates (overridable for custom implementations) */
    protected String[] getDocTemplates();
    
    /** Get class templates (overridable for custom implementations) */
    protected String[] getClassTemplates();
}

Link Management

External documentation linking for comprehensive cross-referencing.

/**
 * Represents a link to external documentation (e.g., Java API docs).
 */
public class LinkArgument {
    /** Set the URL of the external documentation */
    public void setHref(String href);
    
    /** Get the URL of the external documentation */
    public String getHref();
    
    /** Set packages that this link covers (comma-separated) */
    public void setPackages(String packages);
    
    /** Get packages covered by this link */
    public String getPackages();
}

Template System

Customizable template system for documentation generation.

/**
 * Default template information for GroovyDoc generation.
 * Can be overridden for custom documentation formats.
 */
public class GroovyDocTemplateInfo {
    /** Default package-level templates */
    public static final String[] DEFAULT_PACKAGE_TEMPLATES;
    
    /** Default document-level templates */
    public static final String[] DEFAULT_DOC_TEMPLATES;
    
    /** Default class-level templates */
    public static final String[] DEFAULT_CLASS_TEMPLATES;
}

Usage Examples

Basic Documentation Generation

<groovydoc sourcepath="src/main/groovy"
           destdir="docs/groovydoc"
           packagenames="com.example.*"
           windowtitle="My Project API"
           doctitle="My Project API Documentation">
</groovydoc>

Comprehensive Documentation with Custom Settings

<groovydoc sourcepath="src/main/groovy:src/main/java"
           destdir="build/docs/groovydoc"
           packagenames="com.example.*,org.mycompany.*"
           windowtitle="Complete API Reference"
           doctitle="&lt;h1&gt;My Application API&lt;/h1&gt;"
           footer="Copyright 2023 My Company"
           header="&lt;b&gt;My Application v2.0&lt;/b&gt;"
           author="true"
           processScripts="true"
           includeMainForScripts="false"
           access="protected"
           charset="UTF-8"
           fileEncoding="UTF-8">
    
    <overview file="src/overview.html"/>
</groovydoc>

Documentation with External Links

<groovydoc sourcepath="src"
           destdir="docs/api"
           packagenames="com.example.*">
    
    <!-- Link to Java API documentation -->
    <link href="https://docs.oracle.com/en/java/javase/11/docs/api/"
          packages="java.*,javax.*"/>
    
    <!-- Link to Groovy API documentation -->
    <link href="http://docs.groovy-lang.org/latest/html/api/"
          packages="groovy.*,org.codehaus.groovy.*"/>
    
    <!-- Link to Spring Framework documentation -->
    <link href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/"
          packages="org.springframework.*"/>
</groovydoc>

Custom File Extensions and Processing

<groovydoc sourcepath="src:scripts"
           destdir="build/docs"
           packagenames="*"
           extensions=".groovy:.gvy:.gsh:.java"
           processScripts="true"
           includeMainForScripts="true">
    
    <!-- Custom patterns for different source types -->
    <packageset dir="src/main/groovy">
        <include name="**"/>
        <exclude name="**/internal/**"/>
    </packageset>
    
    <packageset dir="src/scripts">
        <include name="**/*.gvy"/>
        <include name="**/*.gsh"/>
    </packageset>
</groovydoc>

Scoped Documentation Generation

<!-- Generate public API documentation only -->
<groovydoc sourcepath="src/main/groovy"
           destdir="docs/public-api"
           access="public"
           packagenames="com.example.api.*">
</groovydoc>

<!-- Generate complete internal documentation -->
<groovydoc sourcepath="src"
           destdir="docs/internal"
           access="private"
           packagenames="com.example.*">
</groovydoc>

Custom Styling and Branding

<groovydoc sourcepath="src/main/groovy"
           destdir="build/docs"
           packagenames="com.example.*"
           windowtitle="MyApp API"
           doctitle="&lt;h1&gt;MyApp API Reference&lt;/h1&gt;"
           header="&lt;div class='header'&gt;&lt;img src='logo.png'/&gt;&lt;/div&gt;"
           footer="&lt;div class='footer'&gt;© 2023 MyCompany&lt;/div&gt;"
           styleSheetFile="docs/custom-styles.css"
           noTimestamp="false"
           noVersionStamp="false">
</groovydoc>

Conditional Documentation Generation

<target name="groovydoc" if="generate.docs">
    <groovydoc sourcepath="${src.dir}"
               destdir="${docs.dir}/groovydoc"
               packagenames="${doc.packages}"
               windowtitle="${project.name} API ${project.version}"
               doctitle="${project.name} API Documentation"
               author="${doc.include.author}">
        
        <link href="${java.api.url}" packages="java.*,javax.*"/>
    </groovydoc>
    
    <!-- Copy additional resources -->
    <copy todir="${docs.dir}/groovydoc">
        <fileset dir="docs/resources" includes="*.css,*.js,*.png"/>
    </copy>
</target>

Advanced Configuration

Template Customization

Custom GroovyDoc implementations can override template methods:

public class CustomGroovydoc extends Groovydoc {
    @Override
    protected String[] getPackageTemplates() {
        return new String[] {
            "custom/packageTemplate.html",
            "custom/packageFrameTemplate.html"
        };
    }
    
    @Override
    protected String[] getDocTemplates() {
        return new String[] {
            "custom/topLevelTemplate.html",
            "custom/indexTemplate.html"
        };
    }
    
    @Override
    protected String[] getClassTemplates() {
        return new String[] {
            "custom/classTemplate.html"
        };
    }
}

Package and File Organization

Organize source files for optimal documentation structure:

<groovydoc destdir="docs/api">
    <!-- Main API packages -->
    <packageset dir="src/main/groovy">
        <include name="com/example/api/**"/>
        <include name="com/example/util/**"/>
        <exclude name="**/impl/**"/>
        <exclude name="**/internal/**"/>
    </packageset>
    
    <!-- Extension packages -->
    <packageset dir="src/extensions/groovy">
        <include name="com/example/extensions/**"/>
    </packageset>
    
    <!-- Script documentation -->
    <sourcepath>
        <pathelement location="src/scripts"/>
    </sourcepath>
</groovydoc>

Documentation Properties

Control documentation generation through system properties:

<groovydoc sourcepath="src"
           destdir="docs"
           packagenames="*"
           verbose="${groovydoc.verbose}"
           author="${groovydoc.include.author}"
           processScripts="${groovydoc.process.scripts}">
    
    <!-- Properties can be set via -D flags or property files -->
    <sysproperty key="groovydoc.template.dir" value="custom-templates"/>
    <sysproperty key="groovydoc.css.theme" value="dark"/>
</groovydoc>

Integration with Build Process

Integrate documentation generation into build lifecycle:

<target name="compile" depends="groovyc"/>

<target name="docs" depends="compile">
    <groovydoc sourcepath="src/main/groovy"
               destdir="build/docs/groovydoc"
               packagenames="*"
               windowtitle="${ant.project.name} ${version}">
        
        <!-- Include version and build information -->
        <header>&lt;b&gt;${ant.project.name} ${version}&lt;/b&gt;&lt;br/&gt;
                Built: ${build.timestamp}</header>
    </groovydoc>
</target>

<target name="package" depends="compile,docs">
    <!-- Include documentation in distribution -->
    <jar destfile="dist/${ant.project.name}-${version}-docs.jar">
        <fileset dir="build/docs/groovydoc"/>
    </jar>
</target>

Install with Tessl CLI

npx tessl i tessl/maven-org-codehaus-groovy--groovy-ant

docs

ant-builder.md

file-utilities.md

groovy-compilation.md

groovy-documentation.md

groovy-execution.md

index.md

tile.json