Repository: incubator-freemarker Updated Branches: refs/heads/3 ed3043856 -> 7338b3255
Added aggregateJavadoc task to the root project. The output contains the API of several modules that are deemed to be used commonly enough. Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/7338b325 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/7338b325 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/7338b325 Branch: refs/heads/3 Commit: 7338b32555473541fc92ab49a6505dc84b3f8489 Parents: ed30438 Author: ddekany <[email protected]> Authored: Mon Jun 19 20:08:15 2017 +0200 Committer: ddekany <[email protected]> Committed: Mon Jun 19 20:08:15 2017 +0200 ---------------------------------------------------------------------- README.md | 14 +- build.gradle | 194 ++++++++++++------- freemarker-converter/build.gradle | 2 + freemarker-core-test-java8/build.gradle | 1 + freemarker-core-test/build.gradle | 1 + freemarker-core/build.gradle | 2 + .../apache/freemarker/core/Configuration.java | 2 +- freemarker-dom/build.gradle | 2 + freemarker-manual/build.gradle | 1 + freemarker-servlet/build.gradle | 2 + freemarker-spring/build.gradle | 2 + freemarker-test-utils/build.gradle | 1 + 12 files changed, 144 insertions(+), 80 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index ca82bfe..72ac49c 100644 --- a/README.md +++ b/README.md @@ -125,10 +125,16 @@ FreeMarker). (On UN*X-like systems you don't need that jar, as our custom To test your build, issue `./gradlew test`. Issued from the top directory, this will run the tests of all modules. -To generate API documentation, issue `./gradlew javadoc`; the output will -appear in the build/docs/api subdirectory of each module. To generate the -FreeMarker Manual, issue `./gradlew manualOffline` (TODO: not yet working); -the output will appear under `freemarker-manual/build/docgen`. +To generate the aggregated API documention (contains the API of several modules +that are deemed to be used commonly enough), issue `./gradlew aggregateJavadoc` +from the root module; the output will appear in the `build/docs/api` +subdirectory. To generate API documentation per module, issue +`./gradlew javadoc`; the output will appear in the build/docs/api subdirectory +of the module. + +To generate the FreeMarker Manual, issue `./gradlew manualOffline` +(TODO: not yet working); the output will appear under +`freemarker-manual/build/docgen`. Eclipse and other IDE setup http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/build.gradle ---------------------------------------------------------------------- diff --git a/build.gradle b/build.gradle index 02b9256..848cc35 100644 --- a/build.gradle +++ b/build.gradle @@ -26,7 +26,9 @@ ext.versionForMf = "2.97.0" allprojects { group = "org.apache.freemarker" version = "${versionCanonical}" - ext.title = null; // Title shown in JavaDoc and other documentation + ext.title = null // Title shown in JavaDoc and other documentation + ext.published = null // To decide if this is a published module (API) or an internal one + ext.inAggregateJavadoc = null // for published project, whether to include this in the main aggregate JavaDoc } title = "Apache FreeMarker" @@ -104,6 +106,85 @@ ext.bannedLibraries = [ } } // each Java version +// Common javadoc configuration: +def javadocCommons = { callerDelegate -> + delegate = callerDelegate + + exclude "**/_*.java" + options.use = true + options.encoding = "UTF-8" + options.docEncoding = "UTF-8" + options.charSet = "UTF-8" + options.locale = "en_US" + options.links = [ "http://docs.oracle.com/javase/8/docs/api/"; ] + doLast { + // We will fix low quality typography of JDK 8 Javadoc here. Bascially we make it look like JDK 7. + + File cssFile = new File(outputDirectory, "stylesheet.css") + assert cssFile.exists() + + // Tell that it's modified: + ant.replaceregexp( + file: cssFile, flags: "gs", encoding: "utf-8", + match: $//\* (Javadoc style sheet) \*//$, replace: $//\* \1 - JDK 8 usability fix regexp substitutions applied \*//$ + ) + + // Remove broken link: + ant.replaceregexp( + file: cssFile, flags: "gs", encoding: "utf-8", + match: $/@import url\('resources/fonts/dejavu.css'\);\s*/$, replace: "" + ) + + // Font family fixes: + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/['"]DejaVu Sans['"]/$, replace: "Arial" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/['"]DejaVu Sans Mono['"]/$, replace: "'Courier New'" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/['"]DejaVu Serif['"]/$, replace: "Arial" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/(?<=[\s,:])serif\b/$, replace: "sans-serif" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/(?<=[\s,:])Georgia,\s*/$, replace: "" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/['"]Times New Roman['"],\s*/$, replace: "" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/(?<=[\s,:])Times,\s*/$, replace: "" + ) + ant.replaceregexp( + file: cssFile, flags: "gsi", encoding: "utf-8", + match: $/(?<=[\s,:])Arial\s*,\s*Arial\b/$, replace: "Arial" + ) + + // "Parameters:", "Returns:", "Throws:", "Since:", "See also:" etc. fixes: + String ddSelectorStart = $/(?:\.contentContainer\s+\.(?:details|description)|\.serializedFormContainer)\s+dl\s+dd\b.*?\{[^\}]*\b/$ + String ddPropertyEnd = $/\b.+?;/$ + // - Put back description (dd) indentation: + ant.replaceregexp( + file: cssFile, flags: "gs", encoding: "utf-8", + match: $/(${ddSelectorStart})margin${ddPropertyEnd}/$, replace: $/\1margin: 5px 0 10px 20px;/$ + ) + // - No monospace font for the description (dd) part: + ant.replaceregexp( + file: cssFile, flags: "gs", encoding: "utf-8", + match: $/(${ddSelectorStart})font-family${ddPropertyEnd}/$, replace: $/\1/$ + ) + } +} + subprojects { apply plugin: "java" apply plugin: "maven" @@ -249,85 +330,48 @@ subprojects { [install.repositories.mavenInstaller, uploadArchives.repositories.mavenDeployer]*.pom*.whenConfigured { pom -> pom.dependencies = pom.dependencies.findAll { dep -> dep.scope != "test" } } - + javadoc { - exclude "**/_*.java" - options.use = true - options.encoding = "UTF-8" - options.docEncoding = "UTF-8" - options.charSet = "UTF-8" - options.locale = "en_US" - options.links = [ "http://docs.oracle.com/javase/8/docs/api/"; ] - doLast { - // We will fix low quality typography of JDK 8 Javadoc here. Bascially we make it look like JDK 7. - - File cssFile = new File(outputDirectory, "stylesheet.css") - assert cssFile.exists() - - // Tell that it's modified: - ant.replaceregexp( - file: cssFile, flags: "gs", encoding: "utf-8", - match: $//\* (Javadoc style sheet) \*//$, replace: $//\* \1 - JDK 8 usability fix regexp substitutions applied \*//$ - ) + javadocCommons(delegate) + } - // Remove broken link: - ant.replaceregexp( - file: cssFile, flags: "gs", encoding: "utf-8", - match: $/@import url\('resources/fonts/dejavu.css'\);\s*/$, replace: "" - ) - - // Font family fixes: - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/['"]DejaVu Sans['"]/$, replace: "Arial" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/['"]DejaVu Sans Mono['"]/$, replace: "'Courier New'" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/['"]DejaVu Serif['"]/$, replace: "Arial" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/(?<=[\s,:])serif\b/$, replace: "sans-serif" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/(?<=[\s,:])Georgia,\s*/$, replace: "" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/['"]Times New Roman['"],\s*/$, replace: "" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/(?<=[\s,:])Times,\s*/$, replace: "" - ) - ant.replaceregexp( - file: cssFile, flags: "gsi", encoding: "utf-8", - match: $/(?<=[\s,:])Arial\s*,\s*Arial\b/$, replace: "Arial" - ) - - // "Parameters:", "Returns:", "Throws:", "Since:", "See also:" etc. fixes: - String ddSelectorStart = $/(?:\.contentContainer\s+\.(?:details|description)|\.serializedFormContainer)\s+dl\s+dd\b.*?\{[^\}]*\b/$ - String ddPropertyEnd = $/\b.+?;/$ - // - Put back description (dd) indentation: - ant.replaceregexp( - file: cssFile, flags: "gs", encoding: "utf-8", - match: $/(${ddSelectorStart})margin${ddPropertyEnd}/$, replace: $/\1margin: 5px 0 10px 20px;/$ - ) - // - No monospace font for the description (dd) part: - ant.replaceregexp( - file: cssFile, flags: "gs", encoding: "utf-8", - match: $/(${ddSelectorStart})font-family${ddPropertyEnd}/$, replace: $/\1/$ - ) - + afterEvaluate { project -> + if (project.ext.published == null) { + throw new GradleScriptException("The \"published\" extension property of the \"${project.path}\" project " + + "wasn't set. Use true for projects that meant to be published to Maven Central. Use false for " + + "projects that are used internally only.", + null); + } + if (project.ext.inAggregateJavadoc == null) { + if (project.ext.published) { + throw new GradleScriptException("The \"inAggregateJavadoc\" extension property of the \"${project.path}\" " + + "project must be set, as it's a published project. Use true for projects that should be part of " + + "the main unified FreeMarker API documentation. Use false for projects that are very rarely " + + "used, and thus should have a " + "separate API javadoc.", + null); + } + } else if (!project.ext.published && project.ext.inAggregateJavadoc) { + throw new GradleScriptException("Do not set the \"inAggregateJavadoc\" property extension to true when " + + "for the \"${project.path}\" project, as the \"published\" extension property is false for it.", + null); } - } + if (project.published && project.inAggregateJavadoc) { + def aggregateJavadoc = rootProject.tasks.getByName('aggregateJavadoc') + def javadoc = project.tasks.getByName('javadoc') + aggregateJavadoc.source javadoc.source + aggregateJavadoc.classpath = files(aggregateJavadoc.classpath, javadoc.classpath) + logger.info "Added ${javadoc.path} input to ${aggregateJavadoc.path}" + } + } } // end subprojects +task aggregateJavadoc(type: Javadoc) { + javadocCommons(delegate) + title "${project.title} ${versionCanonical} API" + destinationDir = new File(project.buildDir, 'api') + // source-s and classpath-s are added later, in the afterEvaluate of subprojects! +} + // TODO Build source distribution files // TODO Build binary distribution files (contains the binaries of all *published* modules) http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-converter/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-converter/build.gradle b/freemarker-converter/build.gradle index 04254f7..c08bad7 100644 --- a/freemarker-converter/build.gradle +++ b/freemarker-converter/build.gradle @@ -20,6 +20,8 @@ title = "Apache FreeMarker Converter" description = """\ FreeMarker template converter tool. Used to convert between template languages.""" +published = true +inAggregateJavadoc = false dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-core-test-java8/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-core-test-java8/build.gradle b/freemarker-core-test-java8/build.gradle index 44b95ae..49e2dfc 100644 --- a/freemarker-core-test-java8/build.gradle +++ b/freemarker-core-test-java8/build.gradle @@ -2,6 +2,7 @@ description = """\ The unit tests of freemarker-core that need Java 8 features. These were moved to a separate project to avoid \ a project that contains java files that require varous Java versions. """ +published = false // Override inherited default Java version: sourceCompatibility = "1.8" http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-core-test/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-core-test/build.gradle b/freemarker-core-test/build.gradle index 6ba033c..0ce6666 100644 --- a/freemarker-core-test/build.gradle +++ b/freemarker-core-test/build.gradle @@ -20,6 +20,7 @@ description = """\ The unit tests of freemarker-core. These tests used to be in freemarker-core, but to avoid depenency loop \ through freemarker-test-utils, they had to be moved into a separate project.""" +published = false dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-core/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-core/build.gradle b/freemarker-core/build.gradle index 5adcf87..96ad717 100644 --- a/freemarker-core/build.gradle +++ b/freemarker-core/build.gradle @@ -25,6 +25,8 @@ title = "Apache FreeMarker Core" description = """\ FreeMarker template engine, core module. This module covers all basic functionality, and is all that's needed for \ many applications.""" +published = true +inAggregateJavadoc = true dependencies { // Note that common dependencies are added in the root project. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java ---------------------------------------------------------------------- diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java b/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java index 87a9a92..4eefda1 100644 --- a/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java +++ b/freemarker-core/src/main/java/org/apache/freemarker/core/Configuration.java @@ -123,7 +123,7 @@ import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; * ... * * // Later, whenever the application needs a template (so you may do this a lot, and from multiple threads): - * {@link Template Template} myTemplate = cfg.{@link #getTemplate(String) getTemplate}("myTemplate.html"); + * {@link Template Template} myTemplate = cfg.{@link #getTemplate(String) getTemplate}("myTemplate.ftlh"); * myTemplate.{@link Template#process(Object, java.io.Writer) process}(dataModel, out);</pre> * * <p>Note that you certainly want to set the {@link #getTemplateLoader templateLoader} setting, as its default http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-dom/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-dom/build.gradle b/freemarker-dom/build.gradle index 0fe800f..2280ebf 100644 --- a/freemarker-dom/build.gradle +++ b/freemarker-dom/build.gradle @@ -21,6 +21,8 @@ title = "Apache FreeMarker DOM support" description = """\ FreeMarker template engine, W3C DOM (XML) wrapping support. \ This is an optional module, useful when the data-model can contain variables that are XML nodes.""" +published = true +inAggregateJavadoc = true dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-manual/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-manual/build.gradle b/freemarker-manual/build.gradle index bec8b70..6a12983 100644 --- a/freemarker-manual/build.gradle +++ b/freemarker-manual/build.gradle @@ -1,4 +1,5 @@ description = "FreeMarker Manual (i.e., the documention)" +published = false dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-servlet/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-servlet/build.gradle b/freemarker-servlet/build.gradle index c0710b9..4e3bd2f 100644 --- a/freemarker-servlet/build.gradle +++ b/freemarker-servlet/build.gradle @@ -22,6 +22,8 @@ description = """\ FreeMarker template engine, Servlet and JSP support. \ This is an optional module, mostly useful in frameworks based on JSP Model-2 architecture, or when custom JSP tags \ need to be called from templates.""" +published = true +inAggregateJavadoc = true dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-spring/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-spring/build.gradle b/freemarker-spring/build.gradle index d5f7e15..3efdbe5 100644 --- a/freemarker-spring/build.gradle +++ b/freemarker-spring/build.gradle @@ -21,6 +21,8 @@ title = "Apache FreeMarker Spring Framework support" description = """\ FreeMarker template engine, Spring Framework support. \ This is an optional module, mostly useful in frameworks based on Spring Framework.""" +published = true +inAggregateJavadoc = true dependencies { compile project(":freemarker-core") http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7338b325/freemarker-test-utils/build.gradle ---------------------------------------------------------------------- diff --git a/freemarker-test-utils/build.gradle b/freemarker-test-utils/build.gradle index 876bd54..fadde2b 100644 --- a/freemarker-test-utils/build.gradle +++ b/freemarker-test-utils/build.gradle @@ -20,6 +20,7 @@ title = "Apache FreeMarker Test Utiltities" description = """\ FreeMarker template engine, testing utilities for internal use; this is not a published module.""" +published = false dependencies { compile project(":freemarker-core")
