Support for asciidoc templates in gdoc

Author: graemerocher

grails-docs/build.gradle

@@ -12,6 +12,7 @@ dependencies {
             'org.yaml:snakeyaml:1.14',
             "org.codehaus.groovy:groovy-ant:$groovyVersion"
 
+    compile 'org.asciidoctor:asciidoctorj:1.5.4'
     compile('org.xhtmlrenderer:core-renderer:R8') {
         exclude group: 'bouncycastle', module:'bcprov-jdk14'
     }

grails-docs/src/main/groovy/grails/doc/DocPublisher.groovy

@@ -15,14 +15,19 @@
 
 package grails.doc
 
+import grails.doc.asciidoc.AsciiDocEngine
 import grails.doc.internal.*
 import groovy.io.FileType
 import groovy.text.Template
 
 import org.apache.commons.logging.LogFactory
+import org.radeox.api.engine.WikiRenderEngine
 import org.radeox.engine.context.BaseInitialRenderContext
+import org.radeox.engine.context.BaseRenderContext
 import org.yaml.snakeyaml.Yaml
 
+import java.util.regex.Pattern
+
 /**
  * Coordinated the DocEngine the produce documentation based on the gdoc format.
  *
@@ -46,6 +51,8 @@ class DocPublisher {
     File images
     /** The directory containing any CSS to use (will override defaults) **/
     File css
+    /** The directory containing any fonts to use (will override defaults) **/
+    File fonts
     /** The directory containing any Javascript to use (will override defaults) **/
     File js
     /** The directory cotnaining any templates to use (will override defaults) **/
@@ -80,13 +87,19 @@ class DocPublisher {
     String logo
     /** HTML markup that renders the right logo */
     String sponsorLogo
+    /**
+     * The source repository
+     */
+    String sourceRepo
 
     /** Properties used to configure the DocEngine */
     Properties engineProperties
 
+    boolean asciidoc = false
+
     def output
-    private context
-    private engine
+    private BaseRenderContext context
+    private WikiRenderEngine engine
     private customMacros = []
 
     DocPublisher() {
@@ -151,7 +164,9 @@ class DocPublisher {
         ant.mkdir(dir: "$refDocsDir/ref")
 
         String imgsDir = new File(refDocsDir, calculatePathToResources("img")).path
+        File fontsDir = new File(refDocsDir, calculatePathToResources("fonts"))
         ant.mkdir(dir: imgsDir)
+        ant.mkdir(dir: fontsDir )
         String cssDir = new File(refDocsDir, calculatePathToResources("css")).path
         ant.mkdir(dir: cssDir)
         String jsDir = new File(refDocsDir, calculatePathToResources("js")).path
@@ -167,6 +182,7 @@ class DocPublisher {
                 fileset(dir: images)
             }
         }
+
         ant.copy(todir: cssDir, overwrite: true) {
             fileset(dir: "${docResources}/css")
         }
@@ -175,6 +191,11 @@ class DocPublisher {
                 fileset(dir: css)
             }
         }
+        if (fonts && fonts.exists()) {
+            ant.copy(todir: fontsDir, overwrite: true, failonerror:false) {
+                fileset(dir: fonts)
+            }
+        }
         ant.copy(todir: jsDir, overwrite: true) {
             fileset(dir: "${docResources}/js")
         }
@@ -201,12 +222,15 @@ class DocPublisher {
         def guideSrcDir = new File(src, "guide")
         def yamlTocFile = new File(guideSrcDir, TOC_FILENAME)
         def guide
+        def ext = asciidoc ? ".adoc" : ".gdoc"
         if (yamlTocFile.exists()) {
-            guide = new YamlTocStrategy(new FileResourceChecker(guideSrcDir)).generateToc(yamlTocFile)
+            def tocStrategy = new YamlTocStrategy(new FileResourceChecker(guideSrcDir), ext)
+            guide = tocStrategy.generateToc(yamlTocFile)
 
             // A set of all gdoc files.
             def files = []
-            guideSrcDir.traverse(type: FileType.FILES, nameFilter: ~/^.+\.gdoc$/) {
+            def pattern = asciidoc ? ~/^.+\.adoc$/ : ~/^.+\.gdoc$/
+            guideSrcDir.traverse(type: FileType.FILES, nameFilter: pattern) {
                 // We need relative file paths with '/' separators, since those
                 // are what are stored in the UserGuideNodes.
                 files << (it.absolutePath - guideSrcDir.absolutePath)[1..-1].
@@ -222,7 +246,8 @@ class DocPublisher {
             }
         }
         else {
-            def files = guideSrcDir.listFiles()?.findAll { it.name.endsWith(".gdoc") } ?: []
+
+            def files = guideSrcDir.listFiles()?.findAll { it.name.endsWith(ext) } ?: []
             guide = new LegacyTocStrategy().generateToc(files)
         }
 
@@ -247,8 +272,8 @@ class DocPublisher {
         def refCategories = files.collect { f ->
             new Expando(
                     name: f.name,
-                    usage: new File("${src}/ref/${f.name}.gdoc"),
-                    sections: f.listFiles().findAll { it.name.endsWith(".gdoc") }.sort())
+                    usage: new File("${src}/ref/${f.name}$ext"),
+                    sections: f.listFiles().findAll { it.name.endsWith(ext) }.sort())
         }
 
         def fullToc = new StringBuilder()
@@ -257,6 +282,7 @@ class DocPublisher {
         def vars = [
             encoding: encoding,
             title: title,
+            docTitle: title,
             subtitle: subtitle,
             footer: footer, // TODO - add a way to specify footer
             authors: authors,
@@ -272,7 +298,8 @@ class DocPublisher {
             resourcesPath: calculatePathToResources(pathToRoot),
             prev: null,
             next: null,
-            legacyLinks: legacyLinks
+            legacyLinks: legacyLinks,
+            sourceRepo: sourceRepo,
         ]
 
         // Build the user guide sections first.
@@ -311,15 +338,16 @@ class DocPublisher {
                 vars.section = section
 
                 new File("${refDocsDir}/ref/${section}").mkdirs()
-                def textiles = f.listFiles().findAll { it.name.endsWith(".gdoc")}.sort()
-                def usageFile = new File("${src}/ref/${section}.gdoc")
+                def textiles = f.listFiles().findAll { it.name.endsWith(ext)}.sort()
+                def usageFile = new File("${src}/ref/${section}${ext}")
                 if (usageFile.exists()) {
                     def data = usageFile.getText("UTF-8")
                     context.set(DocEngine.SOURCE_FILE, usageFile)
                     context.set(DocEngine.CONTEXT_PATH, pathToRoot)
                     context.set(DocEngine.API_CONTEXT_PATH, vars.resourcesPath)
+                    output.warn "Rendering document file $usageFile.name"
                     vars.content = engine.render(data, context)
-
+                    vars.sourcePath = "ref/${section}/$usageFile.name"
                     new File("${refDocsDir}/ref/${section}/Usage.html").withWriter(encoding) {out ->
                         template.make(vars).writeTo(out)
                     }
@@ -330,8 +358,9 @@ class DocPublisher {
                     context.set(DocEngine.SOURCE_FILE, txt.name)
                     context.set(DocEngine.CONTEXT_PATH, pathToRoot)
                     context.set(DocEngine.API_CONTEXT_PATH, vars.resourcesPath)
+                    output.warn "Rendering document file $txt.name"
                     vars.content = engine.render(data, context)
-
+                    vars.sourcePath = "ref/${section}/$txt.name"
                     new File("${refDocsDir}/ref/${section}/${name}.html").withWriter(encoding) {out ->
                         template.make(vars).writeTo(out)
                     }
@@ -404,6 +433,8 @@ class DocPublisher {
         varsCopy.path = path
         varsCopy.level = level
         varsCopy.sectionToc = section.children
+        varsCopy.sourcePath = section.file
+        output.warn "Rendering document file $sourceFile.name"
         varsCopy.content = engine.render(sourceFile.getText("UTF-8"), context)
 
         // First create the section content, which usually consists of a header
@@ -506,7 +537,12 @@ class DocPublisher {
         context = new BaseInitialRenderContext()
         initContext(context, "..")
 
-        engine = new DocEngine(context)
+        if(asciidoc) {
+            engine = new AsciiDocEngine(context)
+        }
+        else {
+            engine = new DocEngine(context)
+        }
 
         engine.engineProperties = props
         context.renderEngine = engine

grails-docs/src/main/groovy/grails/doc/asciidoc/AsciiDocEngine.groovy

@@ -0,0 +1,31 @@
+package grails.doc.asciidoc
+
+import grails.doc.DocEngine
+import groovy.transform.InheritConstructors
+import org.asciidoctor.Options
+import org.asciidoctor.OptionsBuilder
+import org.radeox.api.engine.context.RenderContext
+
+import static org.asciidoctor.Asciidoctor.Factory.create;
+import org.asciidoctor.Asciidoctor;
+/**
+ * Created by graemerocher on 26/09/2016.
+ */
+@InheritConstructors
+class AsciiDocEngine extends DocEngine {
+    Asciidoctor asciidoctor = create();
+
+    @Override
+    String render(String content, RenderContext context) {
+        asciidoctor.convert(content,
+            new OptionsBuilder()
+                .headerFooter(false)
+                .attributes(
+                    'imagesdir': '../img',
+                    'source-highlighter':'coderay'
+                )
+                .get()
+        )
+    }
+
+}

grails-docs/src/main/groovy/grails/doc/gradle/PublishGuide.groovy

@@ -29,6 +29,8 @@ class PublishGuide extends DefaultTask {
     @InputDirectory File resourcesDir = new File(project.projectDir, "resources")
     @Input List propertiesFiles = []
     @Input String language = ""
+    @Input boolean asciidoc = false
+    @Input @Optional String sourceRepo
 
     Collection macros = []
     File workDir = project.buildDir as File
@@ -49,15 +51,17 @@ class PublishGuide extends DefaultTask {
 
         def publisher = new DocPublisher(sourceDir, targetDir)
         publisher.ant = project.ant
+        publisher.asciidoc = asciidoc
         publisher.workDir = workDir
         publisher.apiDir = "${project.outputDir}" as File
         publisher.language = language ?: ''
+        publisher.sourceRepo = sourceRepo
         publisher.images = project.file("${resourcesDir}/img")
         publisher.css = project.file("${resourcesDir}/css")
+        publisher.fonts = project.file("${resourcesDir}/fonts")
         publisher.js = project.file("${resourcesDir}/js")
         publisher.style = project.file("${resourcesDir}/style")
         publisher.version = props."grails.version"
-        publisher.logo = '<a href="http://grails.org" target="_blank"><img alt="Grails Logo" title="The Grails Framework" src="${path}/img/grails.png" border="0"/></a>'
 
         // Override doc.properties properties with their language-specific counterparts (if
         // those are defined). You just need to add entries like es.title or pt_PT.subtitle.

grails-docs/src/main/groovy/grails/doc/internal/YamlTocStrategy.groovy

@@ -8,9 +8,11 @@ import org.yaml.snakeyaml.Yaml
 class YamlTocStrategy {
     private final parser = new Yaml()
     private resourceChecker
+    private String ext = ".gdoc"
 
-    YamlTocStrategy(resourceChecker) {
+    YamlTocStrategy(resourceChecker, String ext = ".gdoc") {
         this.resourceChecker = resourceChecker
+        this.ext = ext
     }
 
     UserGuideNode generateToc(yaml) {
@@ -72,7 +74,7 @@ class YamlTocStrategy {
         }
 
         // First check whether the gdoc file exists in the root directory.
-        def filePath = "${basename}.gdoc"
+        def filePath = "${basename}$ext"
         if (resourceChecker.exists(filePath)) {
             return filePath
         }
@@ -89,7 +91,7 @@ class YamlTocStrategy {
             //    intro/whatsNew/changelog/$basename.gdoc
             //
             for (i in 1..pathElements.size()) {
-                filePath = "${pathElements[-1..-i].join('/')}/${basename}.gdoc"
+                filePath = "${pathElements[-1..-i].join('/')}/${basename}$ext"
                 if (resourceChecker.exists(filePath)) {
                     return filePath
                 }

grails-docs/src/main/resources/grails/doc/doc.properties

@@ -10,4 +10,4 @@ api.java.=http://docs.oracle.com/javase/7/docs/api/
 source.tag.regex=/\s*?def\s+?[a-zA-Z]+?\s*?=\s*?\{\s*?attrs\s*?,{0,1}\s*?body{0,1}\s*?->.+?/
 
 # logos
-logo=<a href="http://grails.org" target="_blank"><img alt="The Grails Framework" src="../img/grails.png" border="0"/></a>
+logo=<a href="http://grails.org" target="_blank"><img alt="The Grails Framework" src="../img/grails-cupsonly-logo-white.svg" border="0"/></a>