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 <[email protected]> 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
