Support multiple templates in log4j-docgen:generate-documentation (#…

…122)

log4j-docgen-maven-plugin/src/main/java/org/apache/logging/log4j/docgen/maven/DocumentationGeneratorMojo.java

@@ -17,8 +17,10 @@
 package org.apache.logging.log4j.docgen.maven;
 
 import java.io.File;
+import java.util.Arrays;
 import java.util.Set;
 import java.util.function.Predicate;
+import java.util.stream.Collectors;
 import org.apache.logging.log4j.docgen.PluginSet;
 import org.apache.logging.log4j.docgen.generator.DocumentationGenerator;
 import org.apache.logging.log4j.docgen.generator.DocumentationGeneratorArgs;
@@ -44,14 +46,14 @@ public class DocumentationGeneratorMojo extends AbstractDocgenMojo {
     /**
      * The template that will be used to document all types.
      */
-    @Parameter(required = true)
-    private DocumentationTemplateMojo indexTemplate;
+    @Parameter
+    private DocumentationTemplateMojo[] indexTemplates;
 
     /**
      * The template that will be used to document types.
      */
-    @Parameter(required = true)
-    private DocumentationTemplateMojo typeTemplate;
+    @Parameter
+    private DocumentationTemplateMojo[] typeTemplates;
 
     @Override
     public void execute() {
@@ -66,12 +68,14 @@ public void execute() {
                 pluginSets,
                 classNameFilter,
                 templateDirectory.toPath(),
-                toApiModel(indexTemplate),
-                toApiModel(typeTemplate));
+                toApiModel(indexTemplates),
+                toApiModel(typeTemplates));
         DocumentationGenerator.generateDocumentation(generatorArgs);
     }
 
-    private static DocumentationTemplate toApiModel(final DocumentationTemplateMojo mojo) {
-        return new DocumentationTemplate(mojo.source, mojo.target);
+    private static Set<DocumentationTemplate> toApiModel(final DocumentationTemplateMojo[] mojos) {
+        return Arrays.stream(mojos)
+                .map(mojo -> new DocumentationTemplate(mojo.source, mojo.target))
+                .collect(Collectors.toSet());
     }
 }

log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/generator/DocumentationGenerator.java

@@ -22,6 +22,7 @@
 import java.nio.file.Path;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import org.apache.logging.log4j.docgen.PluginSet;
@@ -39,20 +40,22 @@ public static void generateDocumentation(final DocumentationGeneratorArgs args)
                 .collect(Collectors.toList());
         final TypeLookup lookup = TypeLookup.of(extendedSets, args.classNameFilter);
         lookup.values()
-                .forEach(sourcedType -> renderType(sourcedType, lookup, args.templateDirectory, args.typeTemplate));
-        renderIndex(lookup, args.templateDirectory, args.indexTemplate);
+                .forEach(sourcedType -> renderType(sourcedType, lookup, args.templateDirectory, args.typeTemplates));
+        renderIndex(lookup, args.templateDirectory, args.indexTemplates);
     }
 
     private static void renderType(
             final ArtifactSourcedType sourcedType,
             final TypeLookup lookup,
             final Path templateDirectory,
-            final DocumentationTemplate template) {
+            final Set<DocumentationTemplate> templates) {
         final Map<String, Object> templateData = Map.of(
                 "sourcedType", sourcedType,
                 "lookup", lookup);
-        final Path targetPath = createTypeTargetPath(sourcedType, template.targetPath);
-        render(templateDirectory, template.name, templateData, targetPath);
+        templates.forEach(template -> {
+            final Path targetPath = createTypeTargetPath(sourcedType, template.targetPath);
+            render(templateDirectory, template.name, templateData, targetPath);
+        });
     }
 
     private static Path createTypeTargetPath(final ArtifactSourcedType sourcedType, final String targetPathPattern) {
@@ -72,8 +75,9 @@ private static String or(@Nullable final String value, final String fallback) {
     }
 
     private static void renderIndex(
-            final TypeLookup lookup, final Path templateDirectory, final DocumentationTemplate template) {
+            final TypeLookup lookup, final Path templateDirectory, final Set<DocumentationTemplate> templates) {
         final Map<String, Object> templateData = Map.of("lookup", lookup);
-        render(templateDirectory, template.name, templateData, Path.of(template.targetPath));
+        templates.forEach(
+                template -> render(templateDirectory, template.name, templateData, Path.of(template.targetPath)));
     }
 }

log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/generator/DocumentationGeneratorArgs.java

@@ -31,20 +31,20 @@ public final class DocumentationGeneratorArgs {
 
     final Path templateDirectory;
 
-    final DocumentationTemplate indexTemplate;
+    final Set<DocumentationTemplate> indexTemplates;
 
-    final DocumentationTemplate typeTemplate;
+    final Set<DocumentationTemplate> typeTemplates;
 
     public DocumentationGeneratorArgs(
             final Set<PluginSet> pluginSets,
             final Predicate<String> classNameFilter,
             final Path templateDirectory,
-            final DocumentationTemplate indexTemplate,
-            final DocumentationTemplate typeTemplate) {
+            final Set<DocumentationTemplate> indexTemplates,
+            final Set<DocumentationTemplate> typeTemplates) {
         this.pluginSets = requireNonNull(pluginSets, "pluginSets");
         this.classNameFilter = requireNonNull(classNameFilter, "classNameFilter");
         this.templateDirectory = requireNonNull(templateDirectory, "templateDirectory");
-        this.indexTemplate = requireNonNull(indexTemplate, "indexTemplate");
-        this.typeTemplate = requireNonNull(typeTemplate, "typeTemplate");
+        this.indexTemplates = requireNonNull(indexTemplates, "indexTemplates");
+        this.typeTemplates = requireNonNull(typeTemplates, "typeTemplates");
     }
 }

log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/generator/DocumentationTemplate.java

@@ -18,6 +18,8 @@
 
 import static java.util.Objects.requireNonNull;
 
+import java.util.Objects;
+
 public final class DocumentationTemplate {
 
     final String name;
@@ -28,4 +30,21 @@ public DocumentationTemplate(final String name, final String targetPath) {
         this.name = requireNonNull(name, "name");
         this.targetPath = requireNonNull(targetPath, "targetPath");
     }
+
+    @Override
+    public boolean equals(Object instance) {
+        if (this == instance) {
+            return true;
+        }
+        if (instance == null || getClass() != instance.getClass()) {
+            return false;
+        }
+        DocumentationTemplate that = (DocumentationTemplate) instance;
+        return Objects.equals(name, that.name) && Objects.equals(targetPath, that.targetPath);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(name, targetPath);
+    }
 }

log4j-docgen/src/test/java/org/apache/logging/log4j/docgen/generator/DocumentationGeneratorTest.java

@@ -16,6 +16,7 @@
  */
 package org.apache.logging.log4j.docgen.generator;
 
+import static java.util.Collections.singleton;
 import static org.apache.logging.log4j.docgen.generator.PluginSetUtils.readDescriptor;
 import static org.apache.logging.log4j.docgen.generator.PluginSetUtils.readDescriptors;
 import static org.apache.logging.log4j.tools.internal.test.util.FileTestUtils.assertDirectoryContentMatches;
@@ -58,10 +59,10 @@ private static void generateDocumentationAndVerifyOutput(
                 pluginSets,
                 className -> !className.startsWith("java."),
                 templateDirectory,
-                new DocumentationTemplate(
-                        "index.adoc.ftl", outputDir.resolve("index.adoc").toString()),
-                new DocumentationTemplate(
-                        "type.adoc.ftl", outputDir.resolve("%a/%c.adoc").toString()));
+                singleton(new DocumentationTemplate(
+                        "index.adoc.ftl", outputDir.resolve("index.adoc").toString())),
+                singleton(new DocumentationTemplate(
+                        "type.adoc.ftl", outputDir.resolve("%a/%c.adoc").toString())));
         DocumentationGenerator.generateDocumentation(generatorArgs);
 
         // Verify the output

log4j-tools-internal-freemarker-util/pom.xml

@@ -37,10 +37,24 @@
   </properties>
 
   <dependencies>
+
     <dependency>
       <groupId>org.freemarker</groupId>
       <artifactId>freemarker</artifactId>
     </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+
   </dependencies>
 
 </project>

log4j-tools-internal-freemarker-util/src/main/java/org/apache/logging/log4j/tools/internal/freemarker/util/FreeMarkerUtils.java

@@ -70,15 +70,22 @@ private static Configuration createConfiguration(final Path templateDirectory) {
     public static void render(
             final Path templateDirectory, final String templateName, final Object templateData, final Path outputFile) {
         try {
+
+            // Render the template
             final Configuration configuration = createConfiguration(templateDirectory);
             final Template template = configuration.getTemplate(templateName);
+            final StringWriter templateOutputWriter = new StringWriter();
+            template.process(templateData, templateOutputWriter);
+            final String templateOutput = templateOutputWriter.toString();
+
+            // Write the template output to the target file
             final Path outputFileParent = outputFile.getParent();
             if (outputFileParent != null) {
                 Files.createDirectories(outputFileParent);
             }
             try (final BufferedWriter outputFileWriter = Files.newBufferedWriter(
                     outputFile, CHARSET, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING)) {
-                template.process(templateData, outputFileWriter);
+                outputFileWriter.write(templateOutput);
             }
         } catch (final Exception error) {
             final String message = String.format(

log4j-tools-internal-freemarker-util/src/test/java/org/apache/logging/log4j/tools/internal/freemarker/util/FreeMarkerUtilsTest.java

@@ -0,0 +1,58 @@
+/*
+ * 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.logging.log4j.tools.internal.freemarker.util;
+
+import static java.nio.file.Files.write;
+import static org.apache.logging.log4j.tools.internal.freemarker.util.FreeMarkerUtils.render;
+import static org.apache.logging.log4j.tools.internal.freemarker.util.FreeMarkerUtils.renderString;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Path;
+import java.nio.file.StandardOpenOption;
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.CleanupMode;
+import org.junit.jupiter.api.io.TempDir;
+
+class FreeMarkerUtilsTest {
+
+    @Test
+    void render_should_work(@TempDir(cleanup = CleanupMode.ON_SUCCESS) final Path tempDir) throws Exception {
+
+        // Create the template file
+        final String templateName = "test.txt.ftl";
+        final Path templateFile = tempDir.resolve(templateName);
+        write(
+                templateFile,
+                "Hello, ${name?capitalize}!".getBytes(StandardCharsets.UTF_8),
+                StandardOpenOption.CREATE_NEW);
+
+        // Render the template
+        final Path outputFile = tempDir.resolve("test.txt");
+        render(tempDir, templateName, Collections.singletonMap("name", "volkan"), outputFile);
+
+        // Verify the generated content
+        assertThat(outputFile).hasContent("Hello, Volkan!");
+    }
+
+    @Test
+    void renderString_should_work() {
+        final String output = renderString("Hello, ${name?capitalize}!", Collections.singletonMap("name", "volkan"));
+        assertThat(output).isEqualTo("Hello, Volkan!");
+    }
+}

src/changelog/.0.x.x/add-multi-doc-generator-template.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns="https://logging.apache.org/xml/ns"
+       xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
+       type="added">
+  <issue id="122" link="https://github.com/apache/logging-log4j-tools/pull/122"/>
+  <description format="asciidoc">Support multiple index and type templates in the `log4j-docgen:generate-documentation` configuration</description>
+</entry>

src/site/antora/modules/ROOT/pages/log4j-docgen-asciidoctor-extension.adoc

@@ -49,6 +49,7 @@ That is, if `true`, `apiref:some.unknown.Class[]` will be converted to `<code>Cl
 Note that this only applies to types where the label is not provided.
 This flag is disabled by default.
 
+[#log4j-docgen-type-target-template]
 `log4j-docgen-type-target-template`::
 The FreeMarker template to produce the link target for individual types documented, for instance:
 +

src/site/antora/modules/ROOT/pages/log4j-docgen-maven-plugin.adoc

@@ -56,18 +56,24 @@ The `generate-documentation` goal generates an AsciiDoc-formatted documentation
   </typeFilter>
 
   <templateDirectory>${project.basedir}/src/docgen-templates</templateDirectory>
-  <indexTemplate>
-    <source>index.adoc.ftl</source>
-    <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/index.adoc</target>
-  </indexTemplate>
-  <typeTemplate>
-    <source>type.adoc.ftl</source>
-    <!-- `target` must be in sync. with the `log4j-docgen-type-template-target` configuration of `log4j-docgen-asciidoctor-extension`! -->
-    <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/%g/%a/%c.adoc</target>
-  </typeTemplate>
+
+  <indexTemplates>
+    <template>
+      <source>index.adoc.ftl</source>
+      <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/index.adoc</target>
+    </template>
+  </indexTemplates>
+
+  <typeTemplates>
+    <template>
+      <source>type.adoc.ftl</source>
+      <target>${project.build.directory}/generated-site/asciidoc/plugin-reference/%g/%a/%c.adoc</target><!--1-->
+    </template>
+  </typeTemplates>
 
 </configuration>
 ----
+<1> `target` must be in sync. with xref:log4j-docgen-asciidoctor-extension.adoc#log4j-docgen-type-target-template[the `log4j-docgen-type-target-template` configuration of `log4j-docgen-asciidoctor-extension`].
 
 The `generate-documentation` goal configuration also accepts the following parameters: