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:14 UTC
[freemarker-generator] 01/01: FREEMARKER-136 freemarker-generator:
Fix broken "site:stage" build
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