The purpose of this post is to find out how the docs plugin works and figure out how to generate documentation close to the code.

This will be done over several posts. The first post will be looking at grails-doc plugin. The second looking into asciidoctor. Finally a summary / conclusion.

Here’s the quick reference link: http://docs.grails.org/latest/ref/Command%20Line/docs.html

First off I’ll create a project:

grails create-app docstest1

Add the plugin to build.gradle:

apply plugin: 'org.grails.grails-doc'

After refreshing the gradle project I find the gradle task in docstest1 -> Tasks -> other -> docs

You can also run it from the command line with:

gradle docs

The created documentation can then be found in the docstest1/build/docs folder and sub-folders.

With this configured you can enrich the documentation with the groovydoc syntax: https://groovy-lang.org/syntax.html

I created a Book domain, and added some groovydoc comments to see where they went:

package no.prpr

/**
 * Book domain class
 */
class Book {

    /**
     * properties constraints
     */
    static constraints = {
    }

    /**
     * The title of the book
     */
    String title
    /**
     * The author
     */
    String author

}

Here’s where they went.

I found some older references to project documentation http://docs.grails.org/3.1.1/guide/single.html#docengine chapter “4.6 Project documentation”. I suspect it is deprecated, but still seems to work.

Trying to generate a guide like this:

toc.yml:

introduction:
    title: Introduction
chapter2:
    title: Chapter 2

introduction.gdoc and chapter2.gdoc just containing a title.