Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Groovy Goodness: Customize Groovydoc Output With Gradle

DZone's Guide to

Groovy Goodness: Customize Groovydoc Output With Gradle

When we write our Groovy application, we of course add documentation to our classes. If we use Gradle to build our project we can run the groovydoc task that is added by the Groovy plugin to generate documentation. Read on and learn how to customize groovydoc output.

· Web Dev Zone
Free Resource

Learn how to build modern digital experience apps with Crafter CMS. Download this eBook now. Brought to you in partnership with Crafter Software

When we write our Groovy application, we of course add documentation to our classes. If we use Gradle to build our project we can run the groovydoc task that is added by the Groovy plugin to generate documentation. We can set document and windows titles and a footer for the generated documentation by changing some properties of the groovydoc task. If we want some further customisation we must take some extra steps. The groovydoc task uses the GroovyDoc tool that is bundled with the Groovy library. GroovyDoc tool uses the GStringTemplateEngine to generate the documentation. The default template files are stored in the package org.codehaus.tools.groovydoc.gstringTemplates. The following files are in the package:

Image title

We can write our own template files if we follow the same package structure and file names. Then when we run the GroovyDoc tool we must make sure our custom template files are used instead of the default ones. If we place our custom files in the class path of the GroovyDoc tool before the Groovy library, then our custom files are used. In our Gradle project, we can create a new source set that will contain our custom template files. Then we configure the classpath property of the groovydoc task and prepend it with the output of our source set. This way we can override the default implementation.

Let's change the classDocName.html template. We make a directory src/groovydoc. Here, we create the directories org/codehaus/groovy/tools/groovy/gstringTemplates/classLevel. Inside the directory we create the file classDocName.html. We use the contents from the default classDocName.html found in the Groovy library and make some small changes. We want to add a Gravatar image to the Authors section. In our source code, we must use the @author tag and include the e-mail address of the user between square brackets. For example, @author Hubert Klein Ikkink [actual-email-address]. In our template file, we will look for the value between the square brackets and replace it with a <img/> HTML tag referencing the Gravatar image.

...
<% if (classDoc.commentText()) { 

   def commentText = classDoc.commentText().replaceAll(/\[(.*)\]/) {
        def md5 = java.security.MessageDigest.getInstance("MD5").digest(it[1].getBytes("UTF-8")).encodeHex()
        "<img src=\"http://www.gravatar.com/avatar/${md5}?s=24\"/>"
   }

%>

    <p>${commentText}</p>
<% } %>
...

We also include a custom header. We set the value via our Gradle build file and it is available in our template file as props.header:

...
<% if (props.header) { %><div>${props.header}</div><% } %>
...

To make CSS changes we add the file stylesheet.css in the directory src/groovydoc/org/codehaus/groovy/tools/groovy/gstringTemplates/topLevel. Also, here we can use the file from the Groovy library as a starting point and make changes in it.

We make the following Gradle build file to support our custom template and reconfigure the groovydoc task:

plugins {
    id "groovy"
}

// Here we add a new SourceSet
// that has a resources directory
// at 'src/groovydoc'. This directory
// contains Groovydoc template files
// we want to override for our project.
sourceSets {
    groovydoc {
        resources {
            srcDir 'src/groovydoc'
        }
    }
}

// Customize groovydoc task that is
// added by the Groovy plugin.
groovydoc {
    // Set document and window titles.
    docTitle = "Sample GroovyDoc"
    windowTitle = "Example customizing GroovyDoc"

    // Set custom header. We will include this
    // in the changed classDocName.html file.
    header = '''\
        <img src="http://www.mrhaki.com/images/haki-logo-black-64.png"/>
        <h2>Sample project</h2>
        '''.stripIndent()

    // Set custom footer for generated documentation.
    footer = """\
        <div class="custom-footer">
            Generated on: ${new Date().format('yyyy-MM-dd HH:mm:ss')}
        </div>""".stripIndent()

    // Change classpath property and include
    // the output of the SourceSet groovydoc.
    // The output contains the changed stylesheet
    // and template file and must be first in the classpath
    // before the files that are bundled with Groovy.
    classpath = sourceSets.groovydoc.output + classpath
}

repositories {
    jcenter()
}

dependencies {
    compile "org.codehaus.groovy:groovy-all:2.4.5"
}

When we make some small changes to stylesheet.css and run the groovydoc task we see the following example output:

Notice that we have our custom header, the Gravatar image, and custom CSS.

Crafter is a modern CMS platform for building modern websites and content-rich digital experiences. Download this eBook now. Brought to you in partnership with Crafter Software.

Topics:
groovy ,gradle ,web dev

Published at DZone with permission of Hubert Klein Ikkink, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}