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:
![](https://johnny.prpr.no/wp-content/uploads/2020/07/Skjermdump-fra-2020-07-06-13-27-59.png)
First error message:
![](https://johnny.prpr.no/wp-content/uploads/2020/07/Skjermdump-fra-2020-07-06-13-51-21.png)
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:
![](https://johnny.prpr.no/wp-content/uploads/2020/07/Skjermdump-fra-2020-07-06-15-08-03.png)
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[]
![](https://johnny.prpr.no/wp-content/uploads/2020/07/Skjermdump-fra-2020-07-06-16-16-26.png)
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)
}