{"id":40465,"date":"2016-10-26T15:08:11","date_gmt":"2016-10-26T09:38:11","guid":{"rendered":"http:\/\/www.tothenew.com\/blog\/?p=40465"},"modified":"2016-10-27T10:13:24","modified_gmt":"2016-10-27T04:43:24","slug":"configuring-grails-3-application-with-ascii-docs","status":"publish","type":"post","link":"https:\/\/www.tothenew.com\/blog\/configuring-grails-3-application-with-ascii-docs\/","title":{"rendered":"Configuring Grails 3 application with ASCII Docs"},"content":{"rendered":"<p>Documentation is a very important aspect\u00a0in any <a title=\"Product Engineering Consulting\" href=\"http:\/\/www.tothenew.com\/product-engineering\">software development<\/a> project because it helps us to understand how our software application works.<\/p>\n<p>Recently, I have been trying to give back to Grails community by updating existing plugins to Grails 3, creating and updating documentation of Grails plugins and by opening bug report. Mostly <a title=\"Grails Development\" href=\"http:\/\/www.tothenew.com\/grails-application-development\">Grails 3 plugins<\/a> are hosted on Github which gives you power of creating your own documentation and publish the same over Github. There are several ways of creating documentation, such as:<\/p>\n<ul>\n<li>Grails Docs<\/li>\n<li>ASCII Docs<\/li>\n<li>GitHub pages etc.<\/li>\n<\/ul>\n<p>Today, we are going to see how we can configure Grails 3 project to build, publish documentation over Github.<\/p>\n<h4>Configure Grails 3 project to build, publish documentation over Github<\/h4>\n<p>So, let&#8217;s first create a basic Grails 3 application using:<\/p>\n<p>[sourcecode]<br \/>\n\tgrails create-app helloDocumentation<br \/>\n[\/sourcecode]<\/p>\n<p>This will create a Grails 3 application. Now, open <code>build.gradle<\/code> and add following plugin under buildscript dependency block:<\/p>\n<p>[sourcecode language=&#8221;groovy&#8221;]<\/p>\n<p>\tclasspath &#8216;org.asciidoctor:asciidoctor-gradle-plugin:1.5.3&#8217;<br \/>\n    classpath &#8216;org.ajoberstar:gradle-git:1.4.2&#8217;<\/p>\n<p>[\/sourcecode]<\/p>\n<p><code>asciidoc-gradle-plugin<\/code> adds a task <strong>asciidoctor<\/strong>. You can configure this task as per your need. Read <a href=\"http:\/\/asciidoctor.org\/docs\/asciidoctor-gradle-plugin\/\">here<\/a> more about configuration.<\/p>\n<p><code>gradle-git<\/code> will add a set of gradle plugins such as:<\/p>\n<ul>\n<li><code>org.ajoberstar.grgit<\/code> &#8211; provides a Grgit instance, allowing interaction with the Git repository the Gradle project is contained in<\/li>\n<li><code>org.ajoberstar.github-pages<\/code> &#8211; publishes files to the gh-pages branch of a Github repository<\/li>\n<li><code>org.ajoberstar.release-base<\/code> &#8211; general structure for inferring a project version and releasing it<\/li>\n<li><code>org.ajoberstar.release-opinion<\/code> &#8211; opinionated defaults for <code>org.ajoberstar.release-base<\/code><\/li>\n<\/ul>\n<p>But, we will only be using <code>org.ajoberstar.github-pages<\/code> to publish the documentation to Github.<\/p>\n<p>Now, create a file <code>documentation.gradle<\/code> under <em>\/gradle\/documentation.gradle<\/em> here we will define gradle tasks to generate documentation. Following is the content of file:<\/p>\n<p>[sourcecode language=&#8221;groovy&#8221;]<\/p>\n<p>buildscript {<br \/>\n    repositories {<br \/>\n        maven { url &#8216;https:\/\/repo.grails.org\/grails\/core&#8217; }<br \/>\n    }<br \/>\n    dependencies {<br \/>\n        classpath &#8216;org.asciidoctor:asciidoctor-gradle-plugin:1.5.3&#8217;<br \/>\n        classpath &#8216;org.asciidoctor:asciidoctorj-epub3:1.5.0-alpha.6&#8217;<br \/>\n        classpath &#8216;org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.11&#8217;<br \/>\n    }<br \/>\n}<\/p>\n<p>apply plugin: &#8216;org.asciidoctor.convert&#8217;<\/p>\n<p>def asciidoctorAttributes = [<br \/>\n        copyright           : &#8216;Apache License, Version 2.0&#8217;,<br \/>\n        docinfo1            : &#8216;true&#8217;,<br \/>\n        doctype             : &#8216;book&#8217;,<br \/>\n        encoding            : &#8216;utf-8&#8217;,<br \/>\n        icons               : &#8216;font&#8217;,<br \/>\n        id                  : project.name + &#8216;:&#8217; + project.version,<br \/>\n        idprefix            : &#8221;,<br \/>\n        idseparator         : &#8216;-&#8216;,<br \/>\n        lang                : &#8216;en&#8217;,<br \/>\n        linkattrs           : true,<br \/>\n        numbered            : &#8221;,<br \/>\n        producer            : &#8216;Asciidoctor&#8217;,<br \/>\n        revnumber           : project.version,<br \/>\n        setanchors          : true,<br \/>\n        &#8216;source-highlighter&#8217; : &#8216;prettify&#8217;,<br \/>\n        toc                 : &#8216;left&#8217;,<br \/>\n        toc2                : &#8221;,<br \/>\n        toclevels           : &#8216;2&#8217;,<br \/>\n        grailsVersion       : project.grailsVersion<br \/>\n]<\/p>\n<p>import org.asciidoctor.gradle.AsciidoctorTask<\/p>\n<p>tasks.withType(AsciidoctorTask) {<br \/>\n    attributes asciidoctorAttributes<br \/>\n    outputDir new File(buildDir, &#8216;docs\/docs&#8217;)<br \/>\n    separateOutputDirs = false<br \/>\n    sourceDir = file(&#8216;src\/docs&#8217;)<br \/>\n    sources {<br \/>\n        include &#8216;index.adoc&#8217;<br \/>\n        include &#8216;ref\/index.adoc&#8217;<br \/>\n    }<br \/>\n}<\/p>\n<p>task asciidoc(type: AsciidoctorTask, description: &#8216;Generates single-page HTML and PDF&#8217;) {<br \/>\n    backends &#8216;html5&#8217;, &#8216;pdf&#8217;<br \/>\n}<\/p>\n<p>task docs(dependsOn: [asciidoc]) &lt;&lt; {<br \/>\n    File dir = new File(buildDir, &#8216;docs\/docs&#8217;)<br \/>\n    [&#8216;pdf&#8217;].each { String ext -&gt;<br \/>\n        File f = new File(dir, &#8216;index.&#8217; + ext)<br \/>\n        if (f.exists()) {<br \/>\n            f.renameTo new File(dir, project.name + &#8216;-&#8216; + project.version + &#8216;.&#8217; + ext)<br \/>\n        }<br \/>\n    }<\/p>\n<p>    File quickRefDir = new File(buildDir, &#8216;docs\/docs\/ref&#8217;)<br \/>\n    [&#8216;pdf&#8217;].each { String ext -&gt;<br \/>\n        File f = new File(quickRefDir, &#8216;index.&#8217; + ext)<br \/>\n        if (f.exists()) {<br \/>\n            f.renameTo new File(quickRefDir, project.name + &#8216;-&#8216; + project.version + &#8216;-&#8216; + &#8216;quickReference&#8217; + &#8216;.&#8217; + ext)<br \/>\n        }<br \/>\n    }<\/p>\n<p>    File ghpages = new File(buildDir, &#8216;docs\/index.html&#8217;)<br \/>\n    if (ghpages.exists()) {<br \/>\n        ghpages.delete()<br \/>\n    }<br \/>\n    ghpages &lt;&lt; file(&#8216;src\/docs\/index.tmpl&#8217;).text.replaceAll(&#8216;@VERSION@&#8217;, project.version)<\/p>\n<p>    copy {<br \/>\n        from &#8216;src\/docs&#8217;<br \/>\n        into new File(buildDir, &#8216;docs&#8217;).path<br \/>\n        include &#8216;**\/*.png&#8217;<br \/>\n    }<br \/>\n}<\/p>\n<p>[\/sourcecode]<\/p>\n<p>Though, one could have this in single <code>build.gradle<\/code> file but I like to keep them organized in different files. So, in <em>documentation.gradle<\/em> we defined following:<\/p>\n<ul>\n<li>Some basic ASCII Docs attributes<\/li>\n<li>Output and Source directory<\/li>\n<li>Which files to include<\/li>\n<li>Type of docs, such as &#8211; single page html and pdf<\/li>\n<li>Template to use for index.html (i.e. index.tmpl)<\/li>\n<\/ul>\n<p>So far, we have logic in place to generate documentation but we still need to configure task to publish it over GitHub. Now, create a new file named <em>\/gradle\/publish.gradle<\/em> with following content:<\/p>\n<p>[sourcecode language=&#8221;groovy&#8221;]<br \/>\n\/\/ Publish gh-pages on github<br \/>\napply plugin: &quot;org.ajoberstar.github-pages&quot;<\/p>\n<p>ext {<br \/>\n    githubApiKey = System.getProperty(&#8216;githubApiKey&#8217;)<br \/>\n}<\/p>\n<p>githubPages {<br \/>\n    repoUri = &#8216;https:\/\/github.com\/&lt;GIT_HUB_SLUG&gt;&#8217;<\/p>\n<p>    credentials {<br \/>\n        username = project.hasProperty(&#8216;githubApiKey&#8217;) ? project.githubApiKey : &#8221;<br \/>\n        password = &#8221;<br \/>\n    }<\/p>\n<p>    pages {<br \/>\n        from &quot;${buildDir}\/docs&quot;<br \/>\n    }<br \/>\n}<\/p>\n<p>task publishDocs(dependsOn: [docs, publishGhPages]) &lt;&lt; {<\/p>\n<p>}<br \/>\n[\/sourcecode]<\/p>\n<p>Basically, here we need permission for publishing to GitHub, so you need to define <code>githubApiKey<\/code> under System properties with your own API key. And you can generate the API Key <a href=\"https:\/\/github.com\/settings\/tokens\" target=\"_blank\">here<\/a>. Otherwise, it will ask you to enter your GitHub username and password everytime you run <code>gradle publishDocs<\/code>.<\/p>\n<p>Finally, the last thing remaining is to include both of these gradle files into main <em>build.gradle<\/em> as follows:<\/p>\n<p>[sourcecode language=&#8221;groovy&#8221;]<br \/>\napply from: &quot;gradle\/documentation.gradle&quot;<br \/>\napply from: &quot;gradle\/publish.gradle&quot;<br \/>\n[\/sourcecode]<\/p>\n<p>Hope this helps, I will write another blog about how to create ASCII Docs.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Documentation is a very important aspect\u00a0in any software development project because it helps us to understand how our software application works. Recently, I have been trying to give back to Grails community by updating existing plugins to Grails 3, creating and updating documentation of Grails plugins and by opening bug report. Mostly Grails 3 plugins [&hellip;]<\/p>\n","protected":false},"author":57,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":3},"categories":[7,1],"tags":[4139,4140,1511,4840,3219],"aioseo_notices":[],"_links":{"self":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/40465"}],"collection":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/users\/57"}],"replies":[{"embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/comments?post=40465"}],"version-history":[{"count":0,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/posts\/40465\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/media?parent=40465"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/categories?post=40465"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.tothenew.com\/blog\/wp-json\/wp\/v2\/tags?post=40465"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}