changeset 13:a628135958e7

USASR-1307: inititial userdoc plugin/task to produce customizable groovy doc
author Dave Smith <smith@nwoca.org>
date Tue, 10 Dec 2013 22:53:57 +0000
parents 0a2819478262
children 9de72de14ab3
files gradle.properties src/main/groovy/org/ssdt_ohio/gradle/plugins/UserDocPlugin.groovy src/main/groovy/org/ssdt_ohio/gradle/tasks/UserDoc.groovy src/main/resources/META-INF/gradle-plugins/userdoc.properties src/test/groovy/org/ssdt_ohio/gradle/plugins/UserDocPluginTest.groovy
diffstat 5 files changed, 261 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/gradle.properties	Wed Aug 14 19:28:51 2013 +0100
+++ b/gradle.properties	Tue Dec 10 22:53:57 2013 +0000
@@ -1,2 +1,2 @@
-version=0.3.0.SNAPSHOT
+version=0.4.0.SNAPSHOT
 group=org.ssdt_ohio
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/main/groovy/org/ssdt_ohio/gradle/plugins/UserDocPlugin.groovy	Tue Dec 10 22:53:57 2013 +0000
@@ -0,0 +1,48 @@
+package org.ssdt_ohio.gradle.plugins
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.internal.plugins.DslObject
+import org.gradle.api.plugins.GroovyPlugin
+import org.gradle.api.plugins.JavaBasePlugin
+import org.gradle.api.plugins.JavaPluginConvention
+import org.gradle.api.tasks.GroovyRuntime
+import org.gradle.api.tasks.GroovySourceSet
+import org.gradle.api.tasks.SourceSet
+import org.ssdt_ohio.gradle.tasks.UserDoc
+
+
+class UserDocPlugin implements Plugin<Project> {
+
+
+    private static final String USERDOC_TASK_NAME = 'userdoc'
+
+    @Override
+    void apply(Project project) {
+
+        project.getPlugins().apply(GroovyPlugin.class)
+        configureUserdoc(project)
+
+    }
+
+    private void configureUserdoc(final Project project) {
+        UserDoc userDoc = project.getTasks().create(USERDOC_TASK_NAME, UserDoc.class);
+        userDoc.setDescription("Generates UserDoc API documentation for the main source code.");
+        userDoc.setGroup(JavaBasePlugin.DOCUMENTATION_GROUP);
+
+        JavaPluginConvention convention = project.getConvention().getPlugin(JavaPluginConvention.class);
+        SourceSet sourceSet = convention.getSourceSets().getByName(SourceSet.MAIN_SOURCE_SET_NAME);
+        userDoc.setClasspath(sourceSet.getOutput().plus(sourceSet.getCompileClasspath()))
+
+
+        GroovySourceSet groovySourceSet = new DslObject(sourceSet).getConvention().getPlugin(GroovySourceSet.class);
+        println "srcdirs: " + groovySourceSet.getGroovy().getSrcDirs()
+        userDoc.setSource(groovySourceSet.getGroovy());
+
+        userDoc.setDestinationDir(new File(project.buildDir, "docs/userdoc"))
+
+        userDoc.setGroovyClasspath(new GroovyRuntime(project).inferGroovyClasspath(project.configurations.compile))
+
+    }
+
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/main/groovy/org/ssdt_ohio/gradle/tasks/UserDoc.groovy	Tue Dec 10 22:53:57 2013 +0000
@@ -0,0 +1,178 @@
+package org.ssdt_ohio.gradle.tasks
+
+import org.codehaus.groovy.tools.groovydoc.ClasspathResourceManager
+import org.codehaus.groovy.tools.groovydoc.FileOutputTool
+import org.codehaus.groovy.tools.groovydoc.GroovyDocTool
+import org.codehaus.groovy.tools.groovydoc.gstringTemplates.GroovyDocTemplateInfo
+import org.gradle.api.InvalidUserDataException
+import org.gradle.api.file.FileCollection
+import org.gradle.api.file.FileVisitDetails
+import org.gradle.api.internal.ClassPathRegistry
+import org.gradle.api.logging.LogLevel
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.SourceTask
+import org.gradle.api.tasks.TaskAction
+
+class UserDoc extends SourceTask {
+
+    private FileCollection groovyClasspath;
+
+    private FileCollection classpath;
+
+    private File destinationDir;
+
+    ClassPathRegistry classPathRegistry
+
+    public UserDoc() {
+        getLogging().captureStandardOutput(LogLevel.INFO);
+        classPathRegistry = getServices().get(ClassPathRegistry.class);
+    }
+
+    @TaskAction
+    protected void generate() {
+        checkGroovyClasspathNonEmpty(getGroovyClasspath().getFiles());
+
+        def tmpDir = new File(project.buildDir, "tmp/userdoc")
+        logger.debug("userdoc tmpDir: $tmpDir")
+        project.delete tmpDir
+        logger.debug("userdoc source: ${super.source.collect { it.toString() }}")
+        project.copy {
+            from super.getSource()
+            into tmpDir
+        }
+
+        def args = [:]
+        args.sourcepath = tmpDir.toString()
+        args.destdir = destinationDir
+
+        Properties properties = new Properties();
+//        properties.setProperty("windowTitle", windowTitle);
+//        properties.setProperty("docTitle", docTitle);
+//        properties.setProperty("footer", footer);
+//        properties.setProperty("header", header);
+//        checkScopeProperties(properties);
+//        properties.setProperty("publicScope", publicScope.toString());
+//        properties.setProperty("protectedScope", protectedScope.toString());
+//        properties.setProperty("packageScope", packageScope.toString());
+//        properties.setProperty("privateScope", privateScope.toString());
+//        properties.setProperty("author", author.toString());
+//        properties.setProperty("processScripts", processScripts.toString());
+//        properties.setProperty("includeMainForScripts", includeMainForScripts.toString());
+//        properties.setProperty("overviewFile", overviewFile != null ? overviewFile.getAbsolutePath() : "");
+//        properties.setProperty("charset", charset != null ? charset : "");
+//        properties.setProperty("fileEncoding", fileEncoding != null ? fileEncoding : "");
+//
+
+        def tool = new GroovyDocTool(new ClasspathResourceManager(),
+                [tmpDir.getPath()] as String[],
+                getDocTemplates(),
+                getPackageTemplates(),
+                getClassTemplates(), [],
+                properties)
+
+        def addFiles = []
+
+        super.getSource().visit { FileVisitDetails d ->
+            if (d.file.isFile()) {
+                addFiles << d.getRelativePath().toString()
+            }
+        }
+
+        tool.add(addFiles)
+        tool.renderToOutput(new FileOutputTool(), destinationDir.getCanonicalPath())
+    }
+
+    private void checkGroovyClasspathNonEmpty(Collection<File> classpath) {
+        if (classpath.isEmpty()) {
+            throw new InvalidUserDataException("You must assign a Groovy library to the groovy configuration!");
+        }
+    }
+
+    /**
+     * Returns the directory to generate the documentation into.
+     *
+     * @return The directory to generate the documentation into
+     */
+    @OutputDirectory
+    public File getDestinationDir() {
+        return destinationDir;
+    }
+
+    /**
+     * Sets the directory to generate the documentation into.
+     */
+    public void setDestinationDir(File destinationDir) {
+        this.destinationDir = destinationDir;
+    }
+
+    /**
+     * Returns the classpath containing the Groovy library to be used.
+     *
+     * @return The classpath containing the Groovy library to be used
+     */
+    @InputFiles
+    public FileCollection getGroovyClasspath() {
+        return groovyClasspath;
+    }
+
+    /**
+     * Sets the classpath containing the Groovy library to be used.
+     */
+    public void setGroovyClasspath(FileCollection groovyClasspath) {
+        this.groovyClasspath = groovyClasspath;
+    }
+
+    /**
+     * Returns the classpath used to locate classes referenced by the documented sources.
+     *
+     * @return The classpath used to locate classes referenced by the documented sources
+     */
+    @InputFiles
+    public FileCollection getClasspath() {
+        return classpath;
+    }
+
+    /**
+     * Sets the classpath used to locate classes referenced by the documented sources.
+     */
+    public void setClasspath(FileCollection classpath) {
+        this.classpath = classpath;
+    }
+
+    /**
+     * Creates and returns an array of package template classpath entries.
+     * <p>
+     * This method is meant to be overridden by custom GroovyDoc implementations, using custom package templates.
+     *
+     * @return an array of package templates, whereas each entry is resolved as classpath entry, defaults to
+     * {@link GroovyDocTemplateInfo#DEFAULT_PACKAGE_TEMPLATES}.
+     */
+    protected String[] getPackageTemplates() {
+        return GroovyDocTemplateInfo.DEFAULT_PACKAGE_TEMPLATES;
+    }
+
+    /**
+     * Creates and returns an array of doc template classpath entries.
+     * <p>
+     * This method is meant to be overridden by custom GroovyDoc implementations, using custom doc templates.
+     *
+     * @return an array of doc templates, whereas each entry is resolved as classpath entry, defaults to
+     * {@link GroovyDocTemplateInfo#DEFAULT_DOC_TEMPLATES}.
+     */
+    protected String[] getDocTemplates() {
+        return GroovyDocTemplateInfo.DEFAULT_DOC_TEMPLATES;
+    }
+
+    /**
+     * Creates and returns an array of class template classpath entries.
+     * <p>
+     * This method is meant to be overridden by custom GroovyDoc implementations, using custom class templates.
+     *
+     * @return an array of class templates, whereas each entry is resolved as classpath entry, defaults to
+     * {@link GroovyDocTemplateInfo#DEFAULT_CLASS_TEMPLATES}.
+     */
+    protected String[] getClassTemplates() {
+        return GroovyDocTemplateInfo.DEFAULT_CLASS_TEMPLATES;
+    }
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/main/resources/META-INF/gradle-plugins/userdoc.properties	Tue Dec 10 22:53:57 2013 +0000
@@ -0,0 +1,1 @@
+implementation-class=org.ssdt_ohio.gradle.plugins.UserDocPlugin
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/test/groovy/org/ssdt_ohio/gradle/plugins/UserDocPluginTest.groovy	Tue Dec 10 22:53:57 2013 +0000
@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2013.  Ohio Department of Education. - All Rights Reserved.
+ * Unauthorized copying of this file, in any medium, is strictly prohibited.
+ * Written by State Software Development Team (http://ssdt.oecn.k12.oh.us/)
+ */
+
+package org.ssdt_ohio.gradle.plugins
+
+import org.gradle.api.Project
+import org.gradle.testfixtures.ProjectBuilder
+import org.junit.Test
+import org.ssdt_ohio.gradle.tasks.UserDoc
+
+
+class UserDocPluginTest {
+
+    @Test
+    public void greeterPluginAddsGreetingTaskToProject() {
+        Project project = ProjectBuilder.builder().withProjectDir(new File('.')).build()
+        project.apply plugin: 'userdoc'
+        project.apply plugin: 'groovy'
+
+        project.dependencies {
+            compile localGroovy()
+        }
+        UserDoc task = project.tasks.userdoc
+        assert task instanceof UserDoc
+
+
+        task.generate()
+
+    }
+}