In this blog post I will try to make write some documentation with ascii-doctor work.

Here’s the asciidoctor user manual: https://asciidoctor.org/docs/user-manual/

First test: Can I simply write adoc’s instead of gdoc’s?

Let’s create a project and see what happens:

grails create-app docstest2

Add the plugin to build.gradle:

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

Reload the gradle project and the task docs will be awailable in the gui, or from the command line.

In this post I will not be looking into the groovydoc’s, so skipping right to generation this structure and files:

First error message:

The groovy/text/Template message can be fixed by including groovy-all, ie. add this dependency to build.gradle:

dependencies {
    docs 'org.codehaus.groovy:groovy-all:2.5.6'
}

This fails with:

After some more googling I found:

• buildscript.dependencies: classpath ‘org.asciidoctor:asciidoctor-gradle-plugin:1.6.1’
• apply plugin: ‘org.asciidoctor.convert’
• the asciidoctor looks in the directory src/docs/asciidoc
• use index.adoc instead of toc.yml
• run the gradle task asciidoctor to create the documentation based on the adoc’s

index.adoc:

:toc: left

= docstest2

[[introduction]]

include::introduction.adoc[]

[[chapter2]]

include::chapter2.adoc[]

The short version for creating asciidocs in grails:

• build.gradle
  • buildscript.dependencies: classpath ‘org.asciidoctor:asciidoctor-gradle-plugin:1.6.1’
  • apply plugin: ‘org.asciidoctor.convert’
• write adoc’s in src/docs/asciidoc
• gradle asciidoctor

Automating the document-generation

You can automate by hooking into the jar task in build.gradle:

jar {
    finalizedBy(groovydoc)
    finalizedBy(asciidoctor)
}