tessl/maven-org-apache-groovy--groovy-groovydoc

A documentation generation tool for Groovy code, part of the Apache Groovy programming language suite

—

Pending

Overview

Eval results

Files

Template Engine

Name: tessl/maven-org-apache-groovy--groovy-groovydoc
Author: tessl

The template engine provides a Groovy-based template processing system that allows complete customization of generated documentation appearance and structure. It processes templates with access to the full documentation model to generate HTML output.

Core API

GroovyDocTemplateEngine

The main template processing engine that applies templates to documentation model objects.

public class GroovyDocTemplateEngine {
    // Simple constructor with single class template
    public GroovyDocTemplateEngine(GroovyDocTool tool, ResourceManager resourceManager, String classTemplate)
    
    // Full constructor with all template types
    public GroovyDocTemplateEngine(GroovyDocTool tool, ResourceManager resourceManager, 
                                  String[] docTemplates, String[] packageTemplates, 
                                  String[] classTemplates, Properties properties)
    
    // Template application methods  
    public String applyClassTemplates(GroovyClassDoc classDoc)                               // Apply class template
    public String applyPackageTemplate(String template, GroovyPackageDoc packageDoc)        // Apply package template  
    public String applyRootDocTemplate(String template, GroovyRootDoc rootDoc)             // Apply root doc template
    public void copyBinaryResource(String template, String destFileName)                   // Copy binary resources
}

ResourceManager

Abstract interface for loading template resources from various sources.

public interface ResourceManager {
    Reader getReader(String resourceName)    // Get reader for template resource
}

Resource Manager Implementations

FileSystemResourceManager

Loads templates from the file system.

public class FileSystemResourceManager implements ResourceManager {
    public FileSystemResourceManager()                     // Default constructor (current directory)
    public FileSystemResourceManager(String basedir)      // Constructor with base directory
    public Reader getReader(String resourceName)          // Load from file system
}

ClasspathResourceManager

Loads templates from the classpath.

public class ClasspathResourceManager implements ResourceManager {
    public ClasspathResourceManager()                           // Default constructor
    public ClasspathResourceManager(ClassLoader classLoader)   // Constructor with custom class loader
    public Reader getReader(String resourceName)               // Load from classpath
    public InputStream getInputStream(String resourceName)      // Get input stream for resource
}

Template Configuration

GroovyDocTemplateInfo

Provides default template configurations and constants.

public class GroovyDocTemplateInfo {
    // Default template arrays
    public static final String[] DEFAULT_DOC_TEMPLATES         // Default top-level templates
    public static final String[] DEFAULT_PACKAGE_TEMPLATES     // Default package templates
    public static final String[] DEFAULT_CLASS_TEMPLATES       // Default class templates
}

The default templates include:

Doc Templates: overview-frame.html, allclasses-frame.html, overview-summary.html, help-doc.html, index.html, package-list, stylesheet.css
Package Templates: package-frame.html, package-summary.html
Class Templates: class.html

Usage Examples

Basic Template Engine Setup

import org.codehaus.groovy.tools.groovydoc.*;
import org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo;

// Use default templates with file system resource manager
ResourceManager resourceManager = new FileSystemResourceManager("templates");
GroovyDocTemplateEngine engine = new GroovyDocTemplateEngine(
    tool,
    resourceManager,
    "class.html"  // Single class template
);

// Use default template configuration
GroovyDocTemplateEngine defaultEngine = new GroovyDocTemplateEngine(
    tool,
    new ClasspathResourceManager(),
    GroovyDocTemplateInfo.DEFAULT_DOC_TEMPLATES,
    GroovyDocTemplateInfo.DEFAULT_PACKAGE_TEMPLATES,
    GroovyDocTemplateInfo.DEFAULT_CLASS_TEMPLATES,
    new Properties()
);

Custom Template Configuration

import java.util.Properties;

// Set up custom templates
String[] docTemplates = {
    "custom-index.html",
    "custom-overview.html", 
    "custom-stylesheet.css"
};

String[] packageTemplates = {
    "custom-package-summary.html",
    "custom-package-frame.html"
};

String[] classTemplates = {
    "custom-class.html"
};

// Configure template properties
Properties templateProps = new Properties();
templateProps.setProperty("windowTitle", "My API Documentation");
templateProps.setProperty("docTitle", "My Project API");
templateProps.setProperty("header", "<b>My Project</b>");
templateProps.setProperty("footer", "<i>Copyright 2023</i>");
templateProps.setProperty("bottom", "Generated by GroovyDoc");

// Create resource manager for custom templates
ResourceManager resourceManager = new FileSystemResourceManager("src/main/templates");

// Create template engine with custom configuration
GroovyDocTemplateEngine engine = new GroovyDocTemplateEngine(
    tool,
    resourceManager,
    docTemplates,
    packageTemplates,
    classTemplates,
    templateProps
);

Template Processing Examples

import org.codehaus.groovy.groovydoc.*;

// Get documentation model objects
GroovyRootDoc rootDoc = tool.getRootDoc();
GroovyClassDoc[] classes = rootDoc.classes();
GroovyPackageDoc[] packages = rootDoc.specifiedPackages();

// Apply class template to generate HTML
for (GroovyClassDoc classDoc : classes) {
    String classHtml = engine.applyClassTemplates(classDoc);
    System.out.println("Generated HTML for " + classDoc.name());
    // classHtml contains the processed HTML for this class
}

// Apply package template
for (GroovyPackageDoc packageDoc : packages) {
    String packageHtml = engine.applyPackageTemplate("package-summary.html", packageDoc);
    System.out.println("Generated package HTML for " + packageDoc.name());
}

// Apply root documentation template
String indexHtml = engine.applyRootDocTemplate("index.html", rootDoc);
System.out.println("Generated index HTML");

Working with Binary Resources

// Copy binary resources (CSS, images, JavaScript) to output
engine.copyBinaryResource("stylesheet.css", "stylesheet.css");
engine.copyBinaryResource("images/logo.png", "images/logo.png");
engine.copyBinaryResource("scripts/doc.js", "scripts/doc.js");

// Resources are copied from the resource manager to the output location

Template Development

Templates are Groovy templates that have access to the documentation model. Here's an example custom class template:

<!-- custom-class.html template -->
<!DOCTYPE html>
<html>
<head>
    <title>${classDoc.qualifiedName()} - ${properties.windowTitle}</title>
    <link rel="stylesheet" type="text/css" href="../stylesheet.css">
</head>
<body>
    <h1>Class ${classDoc.name()}</h1>
    
    <% if (classDoc.commentText()) { %>
    <div class="description">
        ${classDoc.commentText()}
    </div>
    <% } %>
    
    <h2>Methods</h2>
    <% classDoc.methods().each { method -> %>
    <div class="method">
        <h3>${method.name()}${method.signature()}</h3>
        <% if (method.commentText()) { %>
        <p>${method.commentText()}</p>
        <% } %>
        
        <% if (method.parameters().length > 0) { %>
        <h4>Parameters:</h4>
        <ul>
        <% method.parameters().each { param -> %>
            <li><code>${param.name()}</code> (${param.type().typeName()}) 
            <% if (param.defaultValue()) { %>
                - default: ${param.defaultValue()}
            <% } %>
            </li>
        <% } %>
        </ul>
        <% } %>
        
        <% if (method.returnType().typeName() != 'void') { %>
        <h4>Returns:</h4>
        <p><code>${method.returnType().typeName()}</code></p>
        <% } %>
    </div>
    <% } %>
    
    <footer>${properties.footer}</footer>
</body>
</html>

Advanced Template Engine Integration

// Create a custom template engine workflow
public class CustomDocumentationGenerator {
    private final GroovyDocTool tool;
    private final GroovyDocTemplateEngine engine;
    private final OutputTool output;
    
    public CustomDocumentationGenerator(String[] sourcePaths, String templateDir, String outputDir) {
        this.tool = new GroovyDocTool(sourcePaths);
        this.output = new FileOutputTool();
        
        ResourceManager resourceManager = new FileSystemResourceManager(templateDir);
        this.engine = new GroovyDocTemplateEngine(
            tool, resourceManager,
            new String[]{"custom-index.html"},
            new String[]{"custom-package.html"}, 
            new String[]{"custom-class.html"},
            createProperties()
        );
    }
    
    public void generate(List<String> sourceFiles) {
        // Add source files
        tool.add(sourceFiles);
        
        // Generate using custom workflow
        GroovyRootDoc rootDoc = tool.getRootDoc();
        
        // Generate index
        String indexHtml = engine.applyRootDocTemplate("custom-index.html", rootDoc);
        output.writeToOutput("index.html", indexHtml, "UTF-8");
        
        // Generate package documentation
        for (GroovyPackageDoc pkg : rootDoc.specifiedPackages()) {
            String packageHtml = engine.applyPackageTemplate("custom-package.html", pkg);
            output.writeToOutput(pkg.name() + "/package.html", packageHtml, "UTF-8");
        }
        
        // Generate class documentation
        for (GroovyClassDoc classDoc : rootDoc.classes()) {
            String classHtml = engine.applyClassTemplates(classDoc);
            String fileName = classDoc.containingPackage().name().replace('.', '/') + 
                            "/" + classDoc.name() + ".html";
            output.writeToOutput(fileName, classHtml, "UTF-8");
        }
        
        // Copy resources
        engine.copyBinaryResource("custom-stylesheet.css", "stylesheet.css");
    }
    
    private Properties createProperties() {
        Properties props = new Properties();
        props.setProperty("windowTitle", "Custom API Docs");
        props.setProperty("docTitle", "API Documentation");
        return props;
    }
}

// Usage
CustomDocumentationGenerator generator = new CustomDocumentationGenerator(
    new String[]{"src/main/groovy"}, 
    "custom-templates",
    "build/custom-docs"
);
generator.generate(Arrays.asList("com/example/MyClass.groovy"));

Template Variables

Templates have access to several variables and objects:

Documentation Objects: classDoc, packageDoc, rootDoc depending on template type
Properties: properties object containing configured properties
Utility Methods: Various utility methods for formatting and navigation
Tool Reference: Access to the GroovyDocTool instance for additional functionality

This template system provides complete flexibility for customizing the appearance and structure of generated documentation while maintaining access to the full documentation model.

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-groovy--groovy-groovydoc

docs