This is an automated email from the ASF dual-hosted git repository. ddekany pushed a commit to branch FREEMARKER-154 in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
commit 9d04cd95fdc0bdccc32c872e12dd9a48180cb849 Author: ddekany <[email protected]> AuthorDate: Sat Aug 22 19:11:29 2020 +0200 Continued working on porting the .md documentation to XDocBook. Changed the build process a bit as well. --- .../cli/config/TemplateDirectorySupplier.java | 6 +- freemarker-generator-website/README.md | 15 ++- freemarker-generator-website/pom.xml | 31 ++++- .../src/main/docgen/book.xml | 125 +++++++++------------ .../src/main/docgen/docgen.cjson | 4 +- pom.xml | 2 +- 6 files changed, 101 insertions(+), 82 deletions(-) diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java index 8e644a9..886a9ea 100644 --- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java +++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java @@ -95,6 +95,10 @@ public class TemplateDirectorySupplier implements Supplier<List<File>> { } private static boolean isDirectory(File directory) { - return directory != null && directory.exists() && directory.isDirectory() && directory.canRead(); + boolean exists = directory.exists(); + boolean isDirectory = directory.isDirectory(); + boolean canRead = directory.canRead(); + boolean r = directory != null && exists && isDirectory && canRead; + return r; } } diff --git a/freemarker-generator-website/README.md b/freemarker-generator-website/README.md index 2f928b8..7f0008b 100644 --- a/freemarker-generator-website/README.md +++ b/freemarker-generator-website/README.md @@ -1,5 +1,16 @@ Apache FreeMarker Generator Website ============================================================================= -Generates the FreeMarker Generator website, which also contains the documentation; -this is used internally. +Generates the FreeMarker Generator website, which also contains the documentation. +This module is used internally. The output artifact shouldn't be deployed to the +Maven Central. The output is merely to be uploaded to our website. The source code +can be part of the Apache released though. + +Building +-------- + +This module is deliberately not built automatically when you build the top-level +module. To build successfully, first you must build the `freemarker-generator-cli`, +so that we will have `target/appassembler`. Then run the examples in +`target/appassembler`, as the documentation includes the output of some examples. +Only after these run `mvn package` in `freemarker-generator-website`. diff --git a/freemarker-generator-website/pom.xml b/freemarker-generator-website/pom.xml index 898bc90..b199bb8 100644 --- a/freemarker-generator-website/pom.xml +++ b/freemarker-generator-website/pom.xml @@ -35,9 +35,11 @@ <maven.compiler.target>1.8</maven.compiler.target> <websiteOutputDirectory>${project.build.directory}/website</websiteOutputDirectory> - <freemarkerGeneratorBaseDirectory>${project.basedir}/../freemarker-generator-cli</freemarkerGeneratorBaseDirectory> + <freemarkerGeneratorAppHome>${project.basedir}/../freemarker-generator-cli/target/appassembler</freemarkerGeneratorAppHome> <docgenInsertedOutputsDirectory>${project.build.directory}/docgen-insertable-outputs</docgenInsertedOutputsDirectory> - <docgenInsertedExamplesDirectory>${freemarkerGeneratorBaseDirectory}/examples</docgenInsertedExamplesDirectory> + <docgenInsertedExampleTemplatesDirectory>${freemarkerGeneratorAppHome}/examples/templates</docgenInsertedExampleTemplatesDirectory> + <docgenInsertedExampleOutputDirectory>${freemarkerGeneratorAppHome}/target/out</docgenInsertedExampleOutputDirectory> + <docgenInsertedTemplatesDirectory>${freemarkerGeneratorAppHome}/templates</docgenInsertedTemplatesDirectory> </properties> <dependencies> @@ -65,6 +67,15 @@ <arguments> <argument>-classpath</argument> <classpath/> + + <!-- Setting up things without calling the launcher scripts in app/bin: --> + <!-- TODO in freemarker-generator-cli: Ideally, only setting -Dapp.home should be enough. --> + <argument>org.apache.freemarker.generator.cli.Main</argument> + <argument>--config</argument> + <argument>${freemarkerGeneratorAppHome}/config/freemarker-generator.properties</argument> + <argument>--template-dir</argument> + <argument>${freemarkerGeneratorAppHome}/templates</argument> + <argument>org.apache.freemarker.generator.cli.Main</argument> <argument>--help</argument> </arguments> @@ -82,11 +93,17 @@ <arguments> <argument>-classpath</argument> <classpath/> + + <!-- Setting up things without calling the launcher scripts in app/bin: --> + <!-- TODO in freemarker-generator-cli: Ideally, only setting -Dapp.home should be enough. --> <argument>org.apache.freemarker.generator.cli.Main</argument> - <argument>-b</argument> - <argument>${freemarkerGeneratorBaseDirectory}</argument> + <argument>--config</argument> + <argument>${freemarkerGeneratorAppHome}/config/freemarker-generator.properties</argument> + <argument>--template-dir</argument> + <argument>${freemarkerGeneratorAppHome}/templates</argument> + <argument>-t</argument> - <argument>templates/info.ftl</argument> + <argument>freemarker-generator/info.ftl</argument> </arguments> <outputFile>${docgenInsertedOutputsDirectory}/info-template-output.txt</outputFile> </configuration> @@ -111,7 +128,9 @@ <outputDirectory>${websiteOutputDirectory}</outputDirectory> <insertableFiles> <outputs>${docgenInsertedOutputsDirectory}/**</outputs> - <examples>${docgenInsertedExamplesDirectory}/**</examples> + <templates>${docgenInsertedTemplatesDirectory}/**</templates> + <exampleTemplates>${docgenInsertedExampleTemplatesDirectory}/**</exampleTemplates> + <exampleOutputs>${docgenInsertedExampleOutputDirectory}/**</exampleOutputs> </insertableFiles> <customVariables> <version>${project.version}</version> diff --git a/freemarker-generator-website/src/main/docgen/book.xml b/freemarker-generator-website/src/main/docgen/book.xml index 4520c0e..a2a5278 100644 --- a/freemarker-generator-website/src/main/docgen/book.xml +++ b/freemarker-generator-website/src/main/docgen/book.xml @@ -170,7 +170,7 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= the <literal>templates/info.ftl</literal> is particularly helpful to better understand Apache FreeMarker CLI.</para> - <programlisting>> freemarker-generator -t templates/info.ftl + <programlisting>> freemarker-generator -t freemarker-generator/info.ftl [docgen.insertFile "@outputs/info-template-output.txt"]</programlisting> <para>Above:</para> @@ -212,73 +212,9 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= <literal>run-examples.bat</literal> in the Apache FreeMarker Generator installation directory, and have a look at the generated output.</para> - <programlisting>./run-examples.sh -templates/info.ftl -examples/templates/demo.ftl -templates/csv/html/transform.ftl -templates/csv/md/transform.ftl -examples/templates/csv/shell/curl.ftl -examples/templates/csv/md/filter.ftl -examples/templates/csv/fo/transform.ftl -fop -fo target/out/locker-test-users.fo target/out/locker-test-users.pdf -examples/templates/csv/fo/transactions.ftl -fop -fo target/out/transactions.fo target/out/transactions-fo.pdf -templates/csv/html/transform.ftl -wkhtmltopdf -O landscape target/out/transactions.html target/out/transactions-html.pdf -examples/templates/dataframe/example.ftl -examples/templates/accesslog/combined-access.ftl -examples/templates/excel/dataframe/transform.ftl -templates/excel/html/transform.ftl -templates/excel/md/transform.ftl -templates/excel/csv/transform.ftl -examples/templates/excel/csv/custom.ftl -examples/templates/html/csv/dependencies.ftl -examples/templates/json/csv/swagger-endpoints.ftl -templates/json/yaml/transform.ftl -examples/templates/json/md/github-users.ftl -examples/templates/properties/csv/locker-test-users.ftl -examples/data/template -examples/templates/yaml/txt/transform.ftl -templates/yaml/json/transform.ftl -examples/templates/xml/txt/recipients.ftl -Created the following sample files in ./target/out -total 1464 --rw-r--r-- 1 sgoeschl staff 646 Jun 27 16:38 combined-access.log.txt --rw-r--r-- 1 sgoeschl staff 25676 Jun 27 16:38 contract.html --rw-r--r-- 1 sgoeschl staff 7933 Jun 27 16:38 contract.md --rw-r--r-- 1 sgoeschl staff 784 Jun 27 16:38 curl.sh --rw-r--r-- 1 sgoeschl staff 232 Jun 27 16:38 customer.txt --rw-r--r-- 1 sgoeschl staff 6486 Jun 27 16:38 dataframe.txt --rw-r--r-- 1 sgoeschl staff 15613 Jun 27 16:38 demo.txt --rw-r--r-- 1 sgoeschl staff 1310 Jun 27 16:38 dependencies.csv --rw-r--r-- 1 sgoeschl staff 2029 Jun 27 16:38 github-users-curl.md --rw-r--r-- 1 sgoeschl staff 2627 Jun 27 16:38 info.txt --rw-r--r-- 1 sgoeschl staff 8075 Jun 27 16:38 interactive-dataframe.txt --rw-r--r-- 1 sgoeschl staff 66 Jun 27 16:38 interactive-html.txt --rw-r--r-- 1 sgoeschl staff 16 Jun 27 16:38 interactive-json.txt --rw-r--r-- 1 sgoeschl staff 25090 Jun 27 16:38 interactive-swagger.json --rw-r--r-- 1 sgoeschl staff 16870 Jun 27 16:38 interactive-swagger.yaml --rw-r--r-- 1 sgoeschl staff 10 Jun 27 16:38 interactive-xml.txt --rw-r--r-- 1 sgoeschl staff 285 Jun 27 16:38 locker-test-users.csv --rw-r--r-- 1 sgoeschl staff 6341 Jun 27 16:38 locker-test-users.fo --rw-r--r-- 1 sgoeschl staff 5526 Jun 27 16:38 locker-test-users.pdf --rw-r--r-- 1 sgoeschl staff 921 Jun 27 16:38 recipients.txt --rw-r--r-- 1 sgoeschl staff 910 Jun 27 16:38 sales-records.md --rw-r--r-- 1 sgoeschl staff 2453 Jun 27 16:38 swagger-spec.csv --rw-r--r-- 1 sgoeschl staff 25090 Jun 27 16:38 swagger-spec.json --rw-r--r-- 1 sgoeschl staff 16870 Jun 27 16:38 swagger-spec.yaml -drwxr-xr-x 4 sgoeschl staff 128 Jun 27 16:38 template --rw-r--r-- 1 sgoeschl staff 154 Jun 27 16:38 test-multiple-sheets.xlsx.csv --rw-r--r-- 1 sgoeschl staff 1917 Jun 27 16:38 test-multiple-sheets.xlsx.html --rw-r--r-- 1 sgoeschl staff 389 Jun 27 16:38 test-multiple-sheets.xlsx.md --rw-r--r-- 1 sgoeschl staff 155 Jun 27 16:38 test-transform-xls.csv --rw-r--r-- 1 sgoeschl staff 1439 Jun 27 16:38 test.xls.dataframe.txt --rw-r--r-- 1 sgoeschl staff 1556 Jun 27 16:38 test.xls.html --rw-r--r-- 1 sgoeschl staff 1558 Jun 27 16:38 test.xslx.html --rw-r--r-- 1 sgoeschl staff 25757 Jun 27 16:38 transactions-fo.pdf --rw-r--r-- 1 sgoeschl staff 66016 Jun 27 16:38 transactions-html.pdf --rw-r--r-- 1 sgoeschl staff 330128 Jun 27 16:38 transactions.fo --rw-r--r-- 1 sgoeschl staff 51008 Jun 27 16:38 transactions.html</programlisting> + <remark>Removed console output showing list of examples and ls like + output from here. I think it doesn't help users, and had to be generated + in Maven somehow.</remark> <para>Please note that generated PDF files are very likely not found since they require wkhtmltopdf and Apache FOP installation.</para> @@ -293,13 +229,60 @@ drwxr-xr-x 4 sgoeschl staff 128 Jun 27 16:38 template <programlisting>> freemarker-generator -t examples/templates/json/md/github-users.ftl examples/data/json/github-users.json</programlisting> - <para>or pipe a cURL response</para> + <para>or pipe a <literal>curl</literal> response</para> <programlisting>> curl -s https://api.github.com/users | freemarker-generator -t examples/templates/json/md/github-users.ftl --stdin</programlisting> - <para>Below you see the Apache FreeMarker Template</para> + <para>Below you see the Apache FreeMarker Template:</para> - <programlisting role="template">[docgen.insertFile "@examples/templates/json/md/github-users.ftl"]</programlisting> + <programlisting role="template">[docgen.insertFile "@exampleTemplates/json/md/github-users.ftl"]</programlisting> + + <para>This creates the following output:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/examples/github.png" width="100%"/> + </imageobject> + </mediaobject> + </section> + + <section> + <title>CSV to HTML/Markdown Transformation</title> + + <para>Sometimes you have a CSV file which needs to be translated in + Markdown or HTML - there are on-line solutions + available<remark>[removed external product link from here]</remark>, + but having a local solution gives you more flexibility.</para> + + <programlisting>> freemarker-generator -t freemarker-generator/csv/md/transform.ftl examples/data/csv/contract.csv +> freemarker-generator -t freemarker-generator/csv/html/transform.ftl examples/data/csv/contract.csv</programlisting> + + <para>The FreeMarker template is shown below.</para> + + <programlisting role="template">[docgen.insertFile "@templates/freemarker-generator/csv/md/transform.ftl"]</programlisting> + + <para>The resulting file actually looks pleasant when compared to raw + CSV</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/examples/contract.png" width="100%"/> + </imageobject> + </mediaobject> + </section> + + <section> + <title>Transform XML To Plain Text</title> + + <para>Of course you can also transform an XML document:</para> + + <programlisting>> freemarker-generator -t examples/templates/xml/txt/recipients.ftl examples/data/xml/recipients.xml</programlisting> + + <para>This is using the following template:</para> + + <programlisting role="template">[docgen.insertFile "@exampleTemplates/xml/txt/recipients.ftl"]</programlisting> + + <programlisting role="output">[docgen.insertFile "@exampleOutputs/recipients.txt"]</programlisting> </section> </section> </chapter> diff --git a/freemarker-generator-website/src/main/docgen/docgen.cjson b/freemarker-generator-website/src/main/docgen/docgen.cjson index 4152684..8b76b0e 100644 --- a/freemarker-generator-website/src/main/docgen/docgen.cjson +++ b/freemarker-generator-website/src/main/docgen/docgen.cjson @@ -99,5 +99,7 @@ customVariables: { insertableFiles: { outputs: null // Must be overridden by the caller - examples: null // Must be overridden by the caller + templates: null // Must be overridden by the caller + exampleTemplates: null // Must be overridden by the caller + exampleOutputs: null // Must be overridden by the caller } diff --git a/pom.xml b/pom.xml index d74bb29..78484f3 100644 --- a/pom.xml +++ b/pom.xml @@ -78,7 +78,7 @@ <module>freemarker-generator-tools</module> <module>freemarker-generator-cli</module> <module>freemarker-generator-maven-plugin</module> - <module>freemarker-generator-website</module> + <!-- Don't build this automatically: <module>freemarker-generator-website</module> --> </modules> <properties>
