OD-17115 Implementation of DSL documentation in Markdown format

Author: KeyrisXdSnow

buildSrc/apidoc/src/main/groovy/au/com/ish/docs/Configuration.groovy

@@ -13,20 +13,22 @@ import org.gradle.api.file.FileCollection
 class Configuration {
 
     public static final DSL_ANNONATION = 'ish.oncourse.API'
+    protected static final DSL_ANNOTATION_LABEL = '@API'
 
-    public static final RESOUCRCES_DIRECTORY = '../buildSrc/apidoc/src/main/resources/'
-    public static final TEMPLATE_PACKAGE = 'au.com.ish.docs.templates'
+    public static final TEMPLATE_TYPE = 'hbs'
+    public static final RESULT_DOC_TYPE = 'md'
+
+    public static final NULLABLE_ANNONATION = 'javax/annotation/Nullable'
+    public static final NOTNULL_ANNONATION = 'javax/annotation/Nonnull'
+    public static final CAYENNE_ENTITIES_PACKAGE = 'ish/oncourse/server/cayenne/'
 
-    public final String templateBaseDir
-    public final String roomTemplate
-    public final String chapterTemplate
+    public static final TEMPLATES_PACKAGE = 'au.com.ish.docs.templates'
+    public static final RESOUCRCES_DIRECTORY = '../buildSrc/apidoc/src/main/resources/'
+    public static final CHAPTER_TEMPLATE = '/au/com/ish/docs/templates/chapter'
 
-    DslDocsPluginExtension dslDocsPluginExtension
+    private DslDocsPluginExtension dslDocsPluginExtension
 
-    Configuration(String templateBaseDir, String roomTemplate, String chapterTemplate, DslDocsPluginExtension dslDocsPluginExtension) {
-        this.templateBaseDir = templateBaseDir
-        this.roomTemplate = roomTemplate
-        this.chapterTemplate = chapterTemplate
+    Configuration(DslDocsPluginExtension dslDocsPluginExtension) {
         this.dslDocsPluginExtension = dslDocsPluginExtension
     }
 
@@ -39,7 +41,7 @@ class Configuration {
         // we also need to grab _class files in order to get the Cayenne superclasses
         return dslDocsPluginExtension.source
                 .filter { it.absolutePath.endsWith(".java") || it.absolutePath.endsWith(".groovy")}
-                .filter { it.text.contains('@API') || (it.absolutePath.contains("ish/oncourse/server/cayenne")
+                .filter { it.text.contains(DSL_ANNOTATION_LABEL) || (it.absolutePath.contains(CAYENNE_ENTITIES_PACKAGE)
                         && (it.text.contains('public class') || it.text.contains('public abstract class')))
                 }
     }

buildSrc/apidoc/src/main/groovy/au/com/ish/docs/DslDocsPlugin.groovy

@@ -24,13 +24,7 @@ class DslDocsPlugin implements Plugin<Project> {
 
     void apply(Project project) {
 
-        def TEMPLATE_BASEDIR = "/au/com/ish/docs/templates/"
-        Configuration configuration = new Configuration(
-                TEMPLATE_BASEDIR,
-                "index.hbs",
-                TEMPLATE_BASEDIR + "chapter",
-                project.extensions.create(PLUGIN_NAME, DslDocsPluginExtension)
-        )
+        Configuration configuration = new Configuration(project.extensions.create(PLUGIN_NAME, DslDocsPluginExtension))
 
         project.configurations.create(PLUGIN_NAME)
                 .setVisible(false)
@@ -47,15 +41,10 @@ class DslDocsPlugin implements Plugin<Project> {
                 groovyLink.setPackages("groovy.,org.codehaus.groovy.")
                 groovyLink.setHref("http://groovy.codehaus.org/api")
 
-                DslGroovyDocTool docTool = new DslGroovyDocTool(
-                        configuration,
-                        [groovyLink, javaLink].toList(),
-                        project
-                )
-
+                DslGroovyDocTool docTool = new DslGroovyDocTool([groovyLink, javaLink].toList(), project)
+                docTool.cleanUpDirectory(configuration.distationDir)
                 docTool.add(configuration.sourceFiles)
                 docTool.renderToOutput(configuration.distationDir)
-
             }
         }
     }

buildSrc/apidoc/src/main/groovy/au/com/ish/docs/DslGroovyDocTool.groovy

@@ -16,10 +16,13 @@
 
 package au.com.ish.docs
 
-import au.com.ish.docs.generator.DSLGenerator
-import au.com.ish.docs.generator.chapter.ChapterDSLGenerator
-import au.com.ish.docs.generator.root.SectionDSLGenerator
+import au.com.ish.docs.handlebars.EmptyTemplate
+import au.com.ish.docs.handlebars.HandlebarsContext
+import au.com.ish.docs.generator.chapter.ChapterContext
+import au.com.ish.docs.generator.root.SectionContext
+import au.com.ish.docs.helpers.FileHelper
 import au.com.ish.docs.utils.GroovyDocUtils
+import com.github.jknack.handlebars.Options
 import groovyjarjarantlr.RecognitionException
 import groovyjarjarantlr.TokenStreamException
 import org.codehaus.groovy.groovydoc.GroovyClassDoc
@@ -30,35 +33,31 @@ import org.codehaus.groovy.tools.groovydoc.OutputTool
 import org.gradle.api.Project
 import org.gradle.api.file.FileCollection
 
-import java.nio.charset.Charset
 /**
  * This is external interface to the entire tool. First we instantiate the class with the templates
  * and some properties. Then we add all the files we want to document (which causes them to be
  * immediately parsed). And then finally we generate the documentation by rendering the groovy templates.
  */
 class DslGroovyDocTool {
 
-    def log
+	def log
 
-    private final DslGroovyRootDocBuilder rootDocBuilder
-    private final OutputTool output = new FileOutputTool()
-    Project project
+	private Project project
+	private final DslGroovyRootDocBuilder rootDocBuilder
+	private final OutputTool output = new FileOutputTool()
 
-    private Configuration configuration
-
-    /**
+	/**
 	 * Let's set everything up.
 	 *
 	 * @param docTemplate Top level index template for the entire document.
 	 * @param classTemplate A template per class.
 	 * @param links Some external links to other javadocs we might want to link to
 	 */
-	DslGroovyDocTool(Configuration configuration, List<LinkArgument> links, Project project) {
+	DslGroovyDocTool(List<LinkArgument> links, Project project) {
 		this.project = project
-        this.log = project.logger
+		this.log = project.logger
 		this.rootDocBuilder = new DslGroovyRootDocBuilder(this, links)
-        this.configuration = configuration;
-    }
+	}
 
 	/**
 	 * Adding the files to the tool causes them to be parsed by the antlr based groovy or java parser
@@ -87,49 +86,70 @@ class DslGroovyDocTool {
 	 */
 	void renderToOutput(String destdir) throws Exception {
 		GroovyRootDoc rootDoc = rootDocBuilder.resolve()
-        rootDocBuilder.mergeMixins()
+		rootDocBuilder.mergeMixins()
 
-        // only output classes with @API annotation
-        def classes = rootDoc.classes().findAll { GroovyDocUtils.isVisible(it) }.toList()
-//        rootDocBuilder.mergeTraits(classes)
+		// only output classes with @API annotation
+		def classes = rootDoc.classes().findAll { GroovyDocUtils.isVisible(it) }.toList()
+		rootDocBuilder.mergeTraits(classes)
 
-        writeClasses(classes, destdir)
-        writeRoot(classes, project, destdir)
+		writeClasses(classes, destdir)
+		writeRoot(classes, project, destdir)
 
-        // clean up by deleting all the empty folders
-        def emptyDirs = []
+		// clean up by deleting all the empty folders
+		def emptyDirs = []
+		project.fileTree(dir: destdir).visit { v ->
+			File f = v.file
 
-        project.fileTree(dir: destdir).visit { v ->
-            File f = v.file
+			if (f.isDirectory() ) {
+				def children = project.fileTree(f).filter { f.isFile() }.files
+				if (children.size() == 0) {
+					emptyDirs << f
+				}
+			}
+		}
 
-            if (f.isDirectory() ) {
-                def children = project.fileTree(f).filter { f.isFile() }.files
-                if (children.size() == 0) {
-                    emptyDirs << f
-                }
-            }
-        }
+		// reverse so that we do the deepest folders first
+		emptyDirs.reverseEach { it.delete() }
 
-        // reverse so that we do the deepest folders first
-        emptyDirs.reverseEach { it.delete() }
+	}
 
+	void cleanUpDirectory(String destDir) {
+		File dest = new File(destDir)
+		if (dest.exists()) {
+			dest.deleteDir()
+		}
 	}
 
 	private void writeClasses(Collection<GroovyClassDoc> classes, String destdir) throws Exception {
-		DSLGenerator generator = new ChapterDSLGenerator()
-		generator.generate(classes, destdir)
+		classes.each { classDoc ->
+			def context = new ChapterContext.Builder()
+					.setClassDoc(classDoc)
+					.setClasses(classes)
+					.setDistDir(destdir)
+					.setProject(project)
+					.setOutput(output)
+					.setProject(project)
+					.build()
+
+			def _context = new HandlebarsContext(["root": context])
+			def options = new Options(null, null, null, _context, new EmptyTemplate("index.md"), null, null, null, [])
+			FileHelper.renderChapter(classDoc, options)
+		}
 	}
 
-    private void writeRoot(Collection<GroovyClassDoc> classes, Project project, String destdir) throws Exception {
-		//todo
-        String path = destdir + "/index.md"
-        output.makeOutputArea(destdir)
-        new File(path).createNewFile()
-
-        SectionDSLGenerator sectionDSLGenerator = new SectionDSLGenerator(output, project, destdir)
-        def renderedSrc = sectionDSLGenerator.generate(classes, configuration.roomTemplate)
-
-        output.writeToOutput(path, renderedSrc, Charset.defaultCharset().name())
-    }
+	private void writeRoot(Collection<GroovyClassDoc> classes, Project project, String destdir) throws Exception {
+		String path = destdir + "/index.md"
+		def context = new SectionContext.Builder()
+				.setClasses(classes)
+				.setDistDir(destdir)
+				.setProject(project)
+				.setOutput(output)
+				.setProject(project)
+				.build()
+
+		def _context = new HandlebarsContext(["root": context])
+		def options = new Options(null, null, null, _context, new EmptyTemplate("index.md"), null, null, null, [])
+		FileHelper.render(path, options)
+	}
 
 }

buildSrc/apidoc/src/main/groovy/au/com/ish/docs/DslGroovyRootDocBuilder.groovy

@@ -46,10 +46,10 @@ class DslGroovyRootDocBuilder {
 
 	List<LinkArgument> links
 	DslGroovyDocTool tool
-    SimpleGroovyRootDoc rootDoc
-    Properties properties
+	SimpleGroovyRootDoc rootDoc
+	Properties properties
 
-    def log = tool.project.logger
+	def log = tool.project.logger
 
 	DslGroovyRootDocBuilder(DslGroovyDocTool tool, List<LinkArgument> links) {
 		this.tool = tool
@@ -58,10 +58,8 @@ class DslGroovyRootDocBuilder {
 		this.properties = new Properties()
 	}
 
-	private Map<String, GroovyClassDoc> parseGroovy(String src, String packagePath, String file)
-			throws RecognitionException, TokenStreamException {
+	private Map<String, GroovyClassDoc> parseGroovy(String src, String packagePath, String file) throws RecognitionException, TokenStreamException {
 		boolean isJava = file.endsWith(".java")
-
 		SourceBuffer sourceBuffer = new SourceBuffer()
 		UnicodeEscapingReader unicodeReader = new UnicodeEscapingReader(new StringReader(src), sourceBuffer)
 
@@ -103,23 +101,23 @@ class DslGroovyRootDocBuilder {
 		if (path != null && path.length() > 0) {
 			try {
 				String content = ResourceGroovyMethods.getText(new File(path))
-                rootDoc.setDescription(content)
+				rootDoc.setDescription(content)
 			} catch (IOException e) {
 				log.error("Unable to load overview file", e)
 			}
 		}
 	}
 
 	/** Extract the package name from inside the source file */
-    private static String getPackageName(String source) {
+	private static String getPackageName(String source) {
 		if (StringUtils.isNotBlank(source)) {
 			Matcher packageName = source =~ /(?m)^\s*?package\s+?([A-Za-z.0-9]+);?$/
 			if (packageName && packageName[0] && packageName[0][1]) {
 				return (packageName[0] as String[])[1].replaceAll(/\./, '/')
 			}
 		}
 		return "DefaultPackage"
-    }
+	}
 
 	protected void processFile(File srcFile) throws IOException {
 		def src = ResourceGroovyMethods.getText(srcFile)
@@ -129,7 +127,7 @@ class DslGroovyRootDocBuilder {
 		SimpleGroovyPackageDoc packageDoc = (SimpleGroovyPackageDoc) rootDoc.packageNamed(packagePath)
 
 		try {
-            Map<String, GroovyClassDoc> classDocs
+			Map<String, GroovyClassDoc> classDocs
 			classDocs = parseGroovy(src, packagePath, filename)
 			rootDoc.putAllClasses(classDocs)
 
@@ -149,28 +147,28 @@ class DslGroovyRootDocBuilder {
 		return rootDoc
 	}
 
-    /**
-     * Find all the mixin classes and merge their javadoc with the class they are designed to mix to.
-     * So ArtistMixin.class should be added to Artist.class
-     */
-    void mergeMixins() {
-        def mixins = rootDoc.classes().findAll { it.name().endsWith("Mixin") }
-
-        for (GroovyClassDoc mixin : mixins) {
-            def doc = rootDoc.classes().find { it.name() == mixin.name().replace("Mixin", "") }
-            if (doc) {
-                mixin.methods().each { m ->
-                    log.info("Found mixin {}.{} adding to {}", mixin.name(), m.name(), doc.name())
-                    if (m.parameters() && m.parameters()[0]?.name() == "self") {
-                        // use reflection to drop the first fake 'self' param for the mixin method
-                        SimpleGroovyExecutableMemberDoc.metaClass.setAttribute(m, 'parameters', m.parameters().drop(1))
-                        ((SimpleGroovyExecutableMemberDoc)m).setStatic(false)
-                    }
-                    doc.add(m)
-               }
-            }
-        }
-    }
+	/**
+	 * Find all the mixin classes and merge their javadoc with the class they are designed to mix to.
+	 * So ArtistMixin.class should be added to Artist.class
+	 */
+	void mergeMixins() {
+		def mixins = rootDoc.classes().findAll { it.name().endsWith("Mixin") }
+
+		for (GroovyClassDoc mixin : mixins) {
+			def doc = rootDoc.classes().find { it.name() == mixin.name().replace("Mixin", "") }
+			if (doc) {
+				mixin.methods().each { m ->
+					log.info("Found mixin {}.{} adding to {}", mixin.name(), m.name(), doc.name())
+					if (m.parameters() && m.parameters()[0]?.name() == "self") {
+						// use reflection to drop the first fake 'self' param for the mixin method
+						SimpleGroovyExecutableMemberDoc.metaClass.setAttribute(m, 'parameters', m.parameters().drop(1))
+						((SimpleGroovyExecutableMemberDoc)m).setStatic(false)
+					}
+					doc.add(m)
+				}
+			}
+		}
+	}
 
 	void mergeTraits(List<GroovyClassDoc> classes) {
 		for (GroovyClassDoc annotatedClass : classes) {

buildSrc/apidoc/src/main/groovy/au/com/ish/docs/generator/DSLGenerator.groovy

@@ -8,10 +8,10 @@
 
 package au.com.ish.docs.generator
 
-import org.codehaus.groovy.groovydoc.GroovyClassDoc
+import au.com.ish.docs.generator.root.SectionContext
 
-interface DSLGenerator {
+interface DSLGenerator<T extends SectionContext> {
 
-    String generate(Collection<GroovyClassDoc> classes, String templateName) throws Exception
+    String generate(T context) throws Exception
 
 }