freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject incubator-freemarker git commit: Added aggregateJavadoc task to the root project. The output contains the API of several modules that are deemed to be used commonly enough.
Date Mon, 19 Jun 2017 18:08:29 GMT
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 <ddekany@apache.org>
Authored: Mon Jun 19 20:08:15 2017 +0200
Committer: ddekany <ddekany@apache.org>
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")


Mime
View raw message