0
# Documentation Generation
1

2
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.
3

4
## Capabilities
5

6
### Groovydoc Task
7

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

10
```java { .api }
11
/**
12
 * Access to the GroovyDoc tool from Ant for generating API documentation
13
 * from Groovy and Java source files.
14
 */
15
public class Groovydoc extends org.apache.tools.ant.Task {
16
    /** Set source directories to find source files */
17
    public void setSourcepath(Path src);
18
    
19
    /** Set directory where GroovyDoc output will be generated */
20
    public void setDestdir(File dir);
21
    
22
    /** Control whether author information is displayed */
23
    public void setAuthor(boolean author);
24
    
25
    /** Control whether hidden timestamp appears in generated HTML */
26
    public void setNoTimestamp(boolean noTimestamp);
27
    
28
    /** Control whether hidden version stamp appears in generated HTML */
29
    public void setNoVersionStamp(boolean noVersionStamp);
30
    
31
    /** Control whether scripts are processed for documentation */
32
    public void setProcessScripts(boolean processScripts);
33
    
34
    /** Control whether 'main' method is displayed for scripts */
35
    public void setIncludeMainForScripts(boolean includeMainForScripts);
36
    
37
    /** Set filename extensions to process (colon-separated list) */
38
    public void setExtensions(String extensions);
39
    
40
    /** Set package names to process (comma-separated, may use wildcards) */
41
    public void setPackagenames(String packages);
42
    
43
    /** Compatibility method for external file usage (ignored) */
44
    public void setUse(boolean b);
45
    
46
    /** Set title for HTML <title> tag */
47
    public void setWindowtitle(String title);
48
    
49
    /** Set title for overview page */
50
    public void setDoctitle(String htmlTitle);
51
    
52
    /** Set overview file to include in generated documentation */
53
    public void setOverview(File file);
54
    
55
    /** Set access level scope (public, protected, package, private) */
56
    public void setAccess(String access);
57
    
58
    /** Include all classes and members (private scope) */
59
    public void setPrivate(boolean b);
60
    
61
    /** Include only public classes and members */
62
    public void setPublic(boolean b);
63
    
64
    /** Include protected and public classes and members */
65
    public void setProtected(boolean b);
66
    
67
    /** Include package, protected and public classes and members */
68
    public void setPackage(boolean b);
69
    
70
    /** Set footer text for each generated page */
71
    public void setFooter(String footer);
72
    
73
    /** Set header text for each generated page */
74
    public void setHeader(String header);
75
    
76
    /** Set character encoding for generated files */
77
    public void setCharset(String charset);
78
    
79
    /** Set file encoding for writing generated files */
80
    public void setFileEncoding(String fileEncoding);
81
    
82
    /** Set custom CSS stylesheet file */
83
    public void setStyleSheetFile(File styleSheetFile);
84
    
85
    /** Create external documentation link */
86
    public LinkArgument createLink();
87
    
88
    /** Execute documentation generation */
89
    public void execute() throws BuildException;
90
    
91
    /** Get package templates (overridable for custom implementations) */
92
    protected String[] getPackageTemplates();
93
    
94
    /** Get document templates (overridable for custom implementations) */
95
    protected String[] getDocTemplates();
96
    
97
    /** Get class templates (overridable for custom implementations) */
98
    protected String[] getClassTemplates();
99
}
100
```
101

102
### Link Management
103

104
External documentation linking for comprehensive cross-referencing.
105

106
```java { .api }
107
/**
108
 * Represents a link to external documentation (e.g., Java API docs).
109
 */
110
public class LinkArgument {
111
    /** Set the URL of the external documentation */
112
    public void setHref(String href);
113
    
114
    /** Get the URL of the external documentation */
115
    public String getHref();
116
    
117
    /** Set packages that this link covers (comma-separated) */
118
    public void setPackages(String packages);
119
    
120
    /** Get packages covered by this link */
121
    public String getPackages();
122
}
123
```
124

125
### Template System
126

127
Customizable template system for documentation generation.
128

129
```java { .api }
130
/**
131
 * Default template information for GroovyDoc generation.
132
 * Can be overridden for custom documentation formats.
133
 */
134
public class GroovyDocTemplateInfo {
135
    /** Default package-level templates */
136
    public static final String[] DEFAULT_PACKAGE_TEMPLATES;
137
    
138
    /** Default document-level templates */
139
    public static final String[] DEFAULT_DOC_TEMPLATES;
140
    
141
    /** Default class-level templates */
142
    public static final String[] DEFAULT_CLASS_TEMPLATES;
143
}
144
```
145

146
## Usage Examples
147

148
### Basic Documentation Generation
149
```xml
150
<groovydoc sourcepath="src/main/groovy"
151
           destdir="docs/groovydoc"
152
           packagenames="com.example.*"
153
           windowtitle="My Project API"
154
           doctitle="My Project API Documentation">
155
</groovydoc>
156
```
157

158
### Comprehensive Documentation with Custom Settings
159
```xml
160
<groovydoc sourcepath="src/main/groovy:src/main/java"
161
           destdir="build/docs/groovydoc"
162
           packagenames="com.example.*,org.mycompany.*"
163
           windowtitle="Complete API Reference"
164
           doctitle="&lt;h1&gt;My Application API&lt;/h1&gt;"
165
           footer="Copyright 2023 My Company"
166
           header="&lt;b&gt;My Application v2.0&lt;/b&gt;"
167
           author="true"
168
           processScripts="true"
169
           includeMainForScripts="false"
170
           access="protected"
171
           charset="UTF-8"
172
           fileEncoding="UTF-8">
173
    
174
    <overview file="src/overview.html"/>
175
</groovydoc>
176
```
177

178
### Documentation with External Links
179
```xml
180
<groovydoc sourcepath="src"
181
           destdir="docs/api"
182
           packagenames="com.example.*">
183
    
184
    <!-- Link to Java API documentation -->
185
    <link href="https://docs.oracle.com/en/java/javase/11/docs/api/"
186
          packages="java.*,javax.*"/>
187
    
188
    <!-- Link to Groovy API documentation -->
189
    <link href="http://docs.groovy-lang.org/latest/html/api/"
190
          packages="groovy.*,org.codehaus.groovy.*"/>
191
    
192
    <!-- Link to Spring Framework documentation -->
193
    <link href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/"
194
          packages="org.springframework.*"/>
195
</groovydoc>
196
```
197

198
### Custom File Extensions and Processing
199
```xml
200
<groovydoc sourcepath="src:scripts"
201
           destdir="build/docs"
202
           packagenames="*"
203
           extensions=".groovy:.gvy:.gsh:.java"
204
           processScripts="true"
205
           includeMainForScripts="true">
206
    
207
    <!-- Custom patterns for different source types -->
208
    <packageset dir="src/main/groovy">
209
        <include name="**"/>
210
        <exclude name="**/internal/**"/>
211
    </packageset>
212
    
213
    <packageset dir="src/scripts">
214
        <include name="**/*.gvy"/>
215
        <include name="**/*.gsh"/>
216
    </packageset>
217
</groovydoc>
218
```
219

220
### Scoped Documentation Generation
221
```xml
222
<!-- Generate public API documentation only -->
223
<groovydoc sourcepath="src/main/groovy"
224
           destdir="docs/public-api"
225
           access="public"
226
           packagenames="com.example.api.*">
227
</groovydoc>
228

229
<!-- Generate complete internal documentation -->
230
<groovydoc sourcepath="src"
231
           destdir="docs/internal"
232
           access="private"
233
           packagenames="com.example.*">
234
</groovydoc>
235
```
236

237
### Custom Styling and Branding
238
```xml
239
<groovydoc sourcepath="src/main/groovy"
240
           destdir="build/docs"
241
           packagenames="com.example.*"
242
           windowtitle="MyApp API"
243
           doctitle="&lt;h1&gt;MyApp API Reference&lt;/h1&gt;"
244
           header="&lt;div class='header'&gt;&lt;img src='logo.png'/&gt;&lt;/div&gt;"
245
           footer="&lt;div class='footer'&gt;© 2023 MyCompany&lt;/div&gt;"
246
           styleSheetFile="docs/custom-styles.css"
247
           noTimestamp="false"
248
           noVersionStamp="false">
249
</groovydoc>
250
```
251

252
### Conditional Documentation Generation
253
```xml
254
<target name="groovydoc" if="generate.docs">
255
    <groovydoc sourcepath="${src.dir}"
256
               destdir="${docs.dir}/groovydoc"
257
               packagenames="${doc.packages}"
258
               windowtitle="${project.name} API ${project.version}"
259
               doctitle="${project.name} API Documentation"
260
               author="${doc.include.author}">
261
        
262
        <link href="${java.api.url}" packages="java.*,javax.*"/>
263
    </groovydoc>
264
    
265
    <!-- Copy additional resources -->
266
    <copy todir="${docs.dir}/groovydoc">
267
        <fileset dir="docs/resources" includes="*.css,*.js,*.png"/>
268
    </copy>
269
</target>
270
```
271

272
## Advanced Configuration
273

274
### Template Customization
275

276
Custom GroovyDoc implementations can override template methods:
277

278
```java
279
public class CustomGroovydoc extends Groovydoc {
280
    @Override
281
    protected String[] getPackageTemplates() {
282
        return new String[] {
283
            "custom/packageTemplate.html",
284
            "custom/packageFrameTemplate.html"
285
        };
286
    }
287
    
288
    @Override
289
    protected String[] getDocTemplates() {
290
        return new String[] {
291
            "custom/topLevelTemplate.html",
292
            "custom/indexTemplate.html"
293
        };
294
    }
295
    
296
    @Override
297
    protected String[] getClassTemplates() {
298
        return new String[] {
299
            "custom/classTemplate.html"
300
        };
301
    }
302
}
303
```
304

305
### Package and File Organization
306

307
Organize source files for optimal documentation structure:
308

309
```xml
310
<groovydoc destdir="docs/api">
311
    <!-- Main API packages -->
312
    <packageset dir="src/main/groovy">
313
        <include name="com/example/api/**"/>
314
        <include name="com/example/util/**"/>
315
        <exclude name="**/impl/**"/>
316
        <exclude name="**/internal/**"/>
317
    </packageset>
318
    
319
    <!-- Extension packages -->
320
    <packageset dir="src/extensions/groovy">
321
        <include name="com/example/extensions/**"/>
322
    </packageset>
323
    
324
    <!-- Script documentation -->
325
    <sourcepath>
326
        <pathelement location="src/scripts"/>
327
    </sourcepath>
328
</groovydoc>
329
```
330

331
### Documentation Properties
332

333
Control documentation generation through system properties:
334

335
```xml
336
<groovydoc sourcepath="src"
337
           destdir="docs"
338
           packagenames="*"
339
           verbose="${groovydoc.verbose}"
340
           author="${groovydoc.include.author}"
341
           processScripts="${groovydoc.process.scripts}">
342
    
343
    <!-- Properties can be set via -D flags or property files -->
344
    <sysproperty key="groovydoc.template.dir" value="custom-templates"/>
345
    <sysproperty key="groovydoc.css.theme" value="dark"/>
346
</groovydoc>
347
```
348

349
### Integration with Build Process
350

351
Integrate documentation generation into build lifecycle:
352

353
```xml
354
<target name="compile" depends="groovyc"/>
355

356
<target name="docs" depends="compile">
357
    <groovydoc sourcepath="src/main/groovy"
358
               destdir="build/docs/groovydoc"
359
               packagenames="*"
360
               windowtitle="${ant.project.name} ${version}">
361
        
362
        <!-- Include version and build information -->
363
        <header>&lt;b&gt;${ant.project.name} ${version}&lt;/b&gt;&lt;br/&gt;
364
                Built: ${build.timestamp}</header>
365
    </groovydoc>
366
</target>
367

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