You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by sg...@apache.org on 2020/03/08 19:26:13 UTC
[freemarker-generator] branch FREEMARKER-136 created (now 48b6c5b)
This is an automated email from the ASF dual-hosted git repository.
sgoeschl pushed a change to branch FREEMARKER-136
in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git.
at 48b6c5b FREEMARKER-136 freemarker-generator: Fix broken "site:stage" build
This branch includes the following new commits:
new 48b6c5b FREEMARKER-136 freemarker-generator: Fix broken "site:stage" build
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[freemarker-generator] 01/01: FREEMARKER-136 freemarker-generator:
Fix broken "site:stage" build
Posted by sg...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
sgoeschl pushed a commit to branch FREEMARKER-136
in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
commit 48b6c5ba1d26687a9e1cc57ea0faf748eb5baecf
Author: Siegfried Goeschl <si...@gmail.com>
AuthorDate: Sun Mar 8 20:25:58 2020 +0100
FREEMARKER-136 freemarker-generator: Fix broken "site:stage" build
---
.gitignore | 1 +
freemarker-generator-base/pom.xml | 15 ++-
.../base/datasource/DatasourcesSupplier.java | 1 +
.../generator/base/uri/NamedUriParser.java | 2 +-
.../src/site/markdown/index.md | 1 +
freemarker-generator-cli/pom.xml | 16 +--
.../freemarker/generator/cli/config/Suppliers.java | 16 +++
.../src/site/markdown/cli/concepts.md | 124 +++++++++++++++++++++
.../src/site/markdown/index.md | 1 +
freemarker-generator-cli/src/site/site.xml | 24 ++++
freemarker-generator-maven-plugin/pom.xml | 11 +-
.../generator/maven/GeneratingFileVisitor.java | 5 +
.../src/site/markdown/index.md | 1 +
freemarker-generator-tools/pom.xml | 9 +-
.../src/site/markdown/index.md | 1 +
pom.xml | 37 +++---
src/site/markdown/index.md | 8 ++
src/site/site.xml | 43 +++++++
18 files changed, 277 insertions(+), 39 deletions(-)
diff --git a/.gitignore b/.gitignore
index 4718a9d..22adf57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,6 +22,7 @@ build.properties
archive/
ide-dependencies/
META-INF
+velocity.log
out/
bin/
diff --git a/freemarker-generator-base/pom.xml b/freemarker-generator-base/pom.xml
index 6b4cb5b..75e09cd 100644
--- a/freemarker-generator-base/pom.xml
+++ b/freemarker-generator-base/pom.xml
@@ -26,8 +26,8 @@
</parent>
<artifactId>freemarker-generator-base</artifactId>
- <name>Apache FreeMarker Generator: Base</name>
- <description>Common functionality</description>
+ <name>Base</name>
+ <description>Common functionality independent from Apache FreeMarker</description>
<dependencies>
<dependency>
@@ -49,14 +49,21 @@
<reporting>
<plugins>
<plugin>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ </plugin>
+ <plugin>
+ <artifactId>maven-jxr-plugin</artifactId>
+ </plugin>
+ <plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<configuration>
<excludes>
- <exclude>*.md</exclude>
+ <exclude>README.md</exclude>
+ <exclude>src/site/markdown/**/*.md</exclude>
<exclude>**/*.csv</exclude>
<exclude>src/test/data/txt/file_01.txt</exclude>
- </excludes>
+ </excludes>
</configuration>
</plugin>
</plugins>
diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DatasourcesSupplier.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DatasourcesSupplier.java
index 8309939..0f0f740 100644
--- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DatasourcesSupplier.java
+++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/datasource/DatasourcesSupplier.java
@@ -58,6 +58,7 @@ public class DatasourcesSupplier implements Supplier<List<Datasource>> {
*
* @param sources List of source files and/or directories
* @param include Optional include pattern for resolving source files or directory
+ * @param exclude Optional exclude pattern for resolving source files or directory
* @param charset The charset for loading text files
*/
public DatasourcesSupplier(Collection<String> sources, String include, String exclude, Charset charset) {
diff --git a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/NamedUriParser.java b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/NamedUriParser.java
index a5ab42b..e70bf86 100644
--- a/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/NamedUriParser.java
+++ b/freemarker-generator-base/src/main/java/org/apache/freemarker/generator/base/uri/NamedUriParser.java
@@ -33,7 +33,7 @@ import static java.util.regex.Pattern.compile;
* <li>file:///users.csv</li>
* <li>users=file:///users.csv</li>
* <li>users:admin=file:///users.csv</li>
- * <li>users=file:///users.csv#charset=UTF-16&mimetype=text/csv</li>
+ * <li>users=file:///users.csv#charset=UTF-16&mimetype=text/csv</li>
* </ul>
*/
public class NamedUriParser {
diff --git a/freemarker-generator-base/src/site/markdown/index.md b/freemarker-generator-base/src/site/markdown/index.md
new file mode 100644
index 0000000..2fd9f95
--- /dev/null
+++ b/freemarker-generator-base/src/site/markdown/index.md
@@ -0,0 +1 @@
+TBD
\ No newline at end of file
diff --git a/freemarker-generator-cli/pom.xml b/freemarker-generator-cli/pom.xml
index 70855b7..6fafb57 100644
--- a/freemarker-generator-cli/pom.xml
+++ b/freemarker-generator-cli/pom.xml
@@ -26,7 +26,7 @@
</parent>
<artifactId>freemarker-generator-cli</artifactId>
- <name>Apache FreeMarker Generator: CLI</name>
+ <name>CLI</name>
<description>Command-line client for Apache FreeMarker</description>
<build>
@@ -130,15 +130,18 @@
<reporting>
<plugins>
<plugin>
- <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
</plugin>
<plugin>
+ <artifactId>maven-jxr-plugin</artifactId>
+ </plugin>
+ <plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<configuration>
<excludes>
- <exclude>*.md</exclude>
+ <exclude>README.md</exclude>
+ <exclude>src/site/markdown/**/*.md</exclude>
<exclude>.travis.yml</exclude>
<exclude>src/main/resources/patterns/*</exclude>
<exclude>site/sample/*/**</exclude>
@@ -146,13 +149,6 @@
</excludes>
</configuration>
</plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-pmd-plugin</artifactId>
- <configuration>
- <linkXRef>false</linkXRef>
- </configuration>
- </plugin>
</plugins>
</reporting>
diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java
index 0a7a9f2..06dede4 100644
--- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java
+++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/Suppliers.java
@@ -1,3 +1,19 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
package org.apache.freemarker.generator.cli.config;
import freemarker.cache.TemplateLoader;
diff --git a/freemarker-generator-cli/src/site/markdown/cli/concepts.md b/freemarker-generator-cli/src/site/markdown/cli/concepts.md
new file mode 100644
index 0000000..dc95664
--- /dev/null
+++ b/freemarker-generator-cli/src/site/markdown/cli/concepts.md
@@ -0,0 +1,124 @@
+## The Mental Model
+
+* A command line invocation requires 1..n `templates` and 0..n `datasources`
+* A command line invocation is mapped to a series of `transformations`
+* The mapping strategy is either
+ * `aggregating`: each `template` yields one output file based on 0..n `datasources`
+ * `generating`: each `datasources` yields one output per `template`
+* The `transformation` consists of exactly one `template`, 0..n `datasources` and an `output`
+* An `output` is either written to
+ * `stdout`
+ * an output file
+ * an output directory
+* When the output is written to a directory
+ * the structure of the input directory is preserved
+ * the file names can be customized using an output mapping
+
+## Aggregation Versus Generation
+
+This distiniction is only relevant if you have more than one `datasource` for a given `template`
+
+* aggregation will invoke the `template` once with all `datasources`
+* generation will invoke the `template` multiple times with only one `datasources`
+
+### Aggregation
+
+A nice example for `aggregation` is the generation of test user documentation with the following directory layout
+
+```text
+.
+|-- data
+| |-- user-products.csv
+| |-- user-transactions.csv
+| `-- users.csv
+`-- templates
+ |-- test-user-documentation.html.ftl
+ `-- test-user-documentation.md.ftl
+```
+
+We want to transform those three CSV input files into a `Markdown` and `HTML` document copied into an `out` directory
+
+```text
+# Using short options
+> freemarker-cli -t templates -d data -output-dir out
+
+# Using long options
+> freemarker-cli -m aggregate -t templates -d data -output-dir out
+> freemarker-cli --mode aggregate --template templates --datasource data -output-dir out
+```
+
+The invocation would generate the following files
+
+```text
+.
+`-- out
+ |-- test-user-documentation.html
+ `-- test-user-documentation.md
+```
+
+### Generation
+
+#### Source Code Generation
+
+A good example for `generation` is the creation of souce code, e.g. as provided by the `maven-generator-plugin`
+
+```text
+.
+|-- data
+| |-- ProductDao.java.json
+| |-- TransactionDao.java.json
+| `-- UserDao.java.json
+`-- templates
+ `-- generate-dao.ftl
+```
+
+We want to generate three Java files based on JSON files and a single template
+
+```text
+# Using short options
+> freemarker-cli -m generate -t templates -d data -output-dir out
+
+# Using long options
+> freemarker-cli --mode generate --template templates --datasource data -output-dir out
+```
+
+The invocation would generate the following files
+
+```text
+.
+`-- out
+ |-- ProductDao.java
+ |-- TransactionDao.java
+ `-- UserDao.java
+```
+
+#### Configuration File Generations
+
+Another example for `generation` comes from cloud computing, i.e. the generation of configuration files using the following directory layout
+
+```text
+.
+|-- config
+| |-- application.yml
+| `-- nginx.conf
+`-- config.json
+```
+
+We want to generate a set of expanded configuration files
+
+```text
+# Using short options
+> freemarker-cli -m generate -t config -d config.json -output-dir out
+
+# Using long options
+> freemarker-cli --mode generate --template templates --datasource data -output-dir out
+```
+
+which results in the following directory structure
+
+```text
+.
+`-- out
+| |-- application.yml
+| `-- nginx.conf
+```
diff --git a/freemarker-generator-cli/src/site/markdown/index.md b/freemarker-generator-cli/src/site/markdown/index.md
new file mode 100644
index 0000000..2fd9f95
--- /dev/null
+++ b/freemarker-generator-cli/src/site/markdown/index.md
@@ -0,0 +1 @@
+TBD
\ No newline at end of file
diff --git a/freemarker-generator-cli/src/site/site.xml b/freemarker-generator-cli/src/site/site.xml
new file mode 100644
index 0000000..f441c6d
--- /dev/null
+++ b/freemarker-generator-cli/src/site/site.xml
@@ -0,0 +1,24 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project name="FreeMarker Generator">
+ <body>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html" />
+ <item name="Concepts" href="cli/concepts.html" />
+ </menu>
+ </body>
+</project>
\ No newline at end of file
diff --git a/freemarker-generator-maven-plugin/pom.xml b/freemarker-generator-maven-plugin/pom.xml
index 2d19093..e028aa8 100644
--- a/freemarker-generator-maven-plugin/pom.xml
+++ b/freemarker-generator-maven-plugin/pom.xml
@@ -28,7 +28,7 @@
<artifactId>freemarker-generator-maven-plugin</artifactId>
<packaging>maven-plugin</packaging>
- <name>Apache FreeMarker Generator: Maven Plugin</name>
+ <name>Maven Plugin</name>
<description>Maven plugin for Apache FreeMarker</description>
<properties>
@@ -180,11 +180,18 @@
<reporting>
<plugins>
<plugin>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ </plugin>
+ <plugin>
+ <artifactId>maven-jxr-plugin</artifactId>
+ </plugin>
+ <plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<configuration>
<excludes>
- <exclude>*.md</exclude>
+ <exclude>README.md</exclude>
+ <exclude>src/site/markdown/**/*.md</exclude>
<excludde>**/*.json</excludde>
<excludde>src/test/data/generating-file-visitor/data/mydir/bad-extension-test.txt</excludde>
</excludes>
diff --git a/freemarker-generator-maven-plugin/src/main/java/org/apache/freemarker/generator/maven/GeneratingFileVisitor.java b/freemarker-generator-maven-plugin/src/main/java/org/apache/freemarker/generator/maven/GeneratingFileVisitor.java
index 4ca3ce2..7f1fc51 100644
--- a/freemarker-generator-maven-plugin/src/main/java/org/apache/freemarker/generator/maven/GeneratingFileVisitor.java
+++ b/freemarker-generator-maven-plugin/src/main/java/org/apache/freemarker/generator/maven/GeneratingFileVisitor.java
@@ -51,6 +51,11 @@ public class GeneratingFileVisitor extends SimpleFileVisitor<Path> {
/**
* Factory method that calls constructor, added to facilitate testing with jmockit.
+ *
+ * @param config FreeMarker configuration
+ * @param session Maven session
+ * @param extensionToBuilder builder extension
+ * @return GeneratingFileVisitor instance
*/
public static GeneratingFileVisitor create(Configuration config, MavenSession session, Map<String, OutputGeneratorPropertiesProvider> extensionToBuilder) {
return new GeneratingFileVisitor(config, session, extensionToBuilder);
diff --git a/freemarker-generator-maven-plugin/src/site/markdown/index.md b/freemarker-generator-maven-plugin/src/site/markdown/index.md
new file mode 100644
index 0000000..2fd9f95
--- /dev/null
+++ b/freemarker-generator-maven-plugin/src/site/markdown/index.md
@@ -0,0 +1 @@
+TBD
\ No newline at end of file
diff --git a/freemarker-generator-tools/pom.xml b/freemarker-generator-tools/pom.xml
index 8a2d0c8..80815d9 100644
--- a/freemarker-generator-tools/pom.xml
+++ b/freemarker-generator-tools/pom.xml
@@ -26,7 +26,7 @@
</parent>
<artifactId>freemarker-generator-tools</artifactId>
- <name>Apache FreeMarker Generator: Tools</name>
+ <name>Tools</name>
<description>Datasource processing tools for Apache FreeMarker Generator</description>
<properties>
@@ -117,11 +117,16 @@
<reporting>
<plugins>
<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ </plugin>
+ <plugin>
<groupId>org.apache.rat</groupId>
<artifactId>apache-rat-plugin</artifactId>
<configuration>
<excludes>
- <exclude>*.md</exclude>
+ <exclude>README.md</exclude>
+ <exclude>src/site/markdown/**/*.md</exclude>
<exclude>**/*.csv</exclude>
<exclude>src/main/resources/patterns/*</exclude>
</excludes>
diff --git a/freemarker-generator-tools/src/site/markdown/index.md b/freemarker-generator-tools/src/site/markdown/index.md
new file mode 100644
index 0000000..2fd9f95
--- /dev/null
+++ b/freemarker-generator-tools/src/site/markdown/index.md
@@ -0,0 +1 @@
+TBD
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index e5a5d73..a02de99 100644
--- a/pom.xml
+++ b/pom.xml
@@ -28,14 +28,22 @@
<artifactId>freemarker-generator</artifactId>
<packaging>pom</packaging>
<version>0.1.0-SNAPSHOT</version>
- <name>Apache FreeMarker Generator: Parent</name>
- <url>https://freemarker.apache.org/</url>
+ <name>Apache FreeMarker Generator</name>
+ <url>https://freemarker-generator.apache.org/</url>
<issueManagement>
<system>jira</system>
<url>https://issues.apache.org/jira/browse/FREEMARKER/</url>
</issueManagement>
+ <distributionManagement>
+ <site>
+ <id>apache.website</id>
+ <name>Apache Website</name>
+ <url>scp://people.apache.org/www/freemarker-generator/</url>
+ </site>
+ </distributionManagement>
+
<mailingLists>
<mailingList>
<name>FreeMarker developer list</name>
@@ -73,10 +81,10 @@
</modules>
<properties>
- <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <freemarker.version>2.3.29</freemarker.version>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
- <freemarker.version>2.3.29</freemarker.version>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<developers>
@@ -154,6 +162,10 @@
<version>3.1.1</version>
</plugin>
<plugin>
+ <artifactId>maven-jxr-plugin</artifactId>
+ <version>3.0.0</version>
+ </plugin>
+ <plugin>
<artifactId>maven-plugin-plugin</artifactId>
<version>3.6.0</version>
</plugin>
@@ -175,7 +187,7 @@
</plugin>
<plugin>
<artifactId>maven-site-plugin</artifactId>
- <version>3.7.1</version>
+ <version>3.8.2</version>
</plugin>
<plugin>
<artifactId>maven-source-plugin</artifactId>
@@ -246,26 +258,11 @@
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
<linkXRef>false</linkXRef>
</configuration>
</plugin>
- <plugin>
- <groupId>org.apache.rat</groupId>
- <artifactId>apache-rat-plugin</artifactId>
- <configuration>
- <excludes>
- <exclude>*.md</exclude>
- <excludde>**/*.json</excludde>
- <excludde>**/*.csv</excludde>
- </excludes>
- </configuration>
- </plugin>
</plugins>
</reporting>
</project>
\ No newline at end of file
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..6b9eb0d
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,8 @@
+The Apache FreeMarker Generator projects provides additional tools to generate textual ouptut using [Apache FreeMarker](https://freemarker.apache.org).
+
+| Name | Description |
+| --------------------- | ----------------------------------------------------------------- |
+| Base | Common functionality independent from Apache FreeMarker |
+| Tools | Datasource processing tools for Apache FreeMarker Generator |
+| CLI | Command-line client for Apache FreeMarker |
+| Maven Plugin | Maven plugin for Apache FreeMarker |
\ No newline at end of file
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000..33495fe
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,43 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project name="FreeMarker Generator">
+
+ <bannerRight>
+ <name>Apache FreeMarker</name>
+ <src>https://freemarker.apache.org/logo.png</src>
+ <href>https://freemarker.apache.org/</href>
+ </bannerRight>
+
+ <skin>
+ <groupId>org.apache.maven.skins</groupId>
+ <artifactId>maven-fluido-skin</artifactId>
+ <version>1.8</version>
+ </skin>
+
+ <body>
+ <breadcrumbs>
+ <item name="Apache" href="https://www.apache.org"/>
+ <item name="FreeMarker" href="https://freemarker.apache.org"/>
+ <item name="Generator" href="https://freemarker-generator.apache.org/index.html"/>
+ </breadcrumbs>
+ <menu name="Overview">
+ <item name="Introduction" href="index.html" />
+ </menu>
+ <menu ref="modules" />
+ <menu ref="reports" inherit="bottom" />
+ </body>
+</project>
\ No newline at end of file