From 84f14212f46e1b1c4f2fa59db25bb1605354e0d7 Mon Sep 17 00:00:00 2001
From: "Erik C. Thauvin" <erik@thauvin.net>
Date: Sun, 5 Nov 2023 22:42:51 -0800
Subject: [PATCH] Added method to reset the Dokka plugins

Added examples for generating documenation in HTML and markdown formats
---
 README.md                                     |  8 ++-
 examples/.idea/misc.xml                       |  2 +
 examples/lib/bld/bld-wrapper.properties       |  2 +-
 .../bld/java/com/example/ExampleBuild.java    | 29 ++++++++++
 .../CompileKotlinOperationBuild.java          |  1 +
 .../bld/extension/dokka/DokkaOperation.java   | 57 ++++++++++++-------
 .../extension/dokka/DokkaOperationTest.java   |  8 +--
 7 files changed, 78 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 239a949..ae5a4db 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
 To install, please refer to the [extensions documentation](https://github.com/rife2/bld/wiki/Extensions).
 
 ## Compile Kotlin Source Code
+
 To compile the source code located in `src/main/kotlin` and `src/test/kotlin` from the current project:
 
 ```java
@@ -26,6 +27,7 @@ public void compile() throws IOException {
 ```text
 ./bld compile
 ```
+
 - [View Examples Project](https://github.com/rife2/bld-kotlin/tree/main/examples/)
 
 Please check the [Compile Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/CompileKotlinOperation.html#method-summary)
@@ -43,10 +45,12 @@ public void javadoc() throws ExitStatusException, IOException, InterruptedExcept
             .execute();
 }
 ```
-```
+
+```text
 ./bld javadoc
 ```
+
 - [View Examples Project](https://github.com/rife2/bld-kotlin/tree/main/examples/)
 
-Please check the [Dokka Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/dokka/DokkaOperation.html)
+Please check the [Dokka Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/dokka/DokkaOperation.html#method-summary)
 for all available configuration options.
diff --git a/examples/.idea/misc.xml b/examples/.idea/misc.xml
index ba68603..87b25c5 100644
--- a/examples/.idea/misc.xml
+++ b/examples/.idea/misc.xml
@@ -3,6 +3,8 @@
   <component name="EntryPointsManager">
     <pattern value="com.example.ExampleBuild" />
     <pattern value="com.example.ExampleBuild" method="javadoc" />
+    <pattern value="com.example.ExampleBuild" method="dokkaHtml" />
+    <pattern value="com.example.ExampleBuild" method="dokkaGfm" />
   </component>
   <component name="PDMPlugin">
     <option name="customRuleSets">
diff --git a/examples/lib/bld/bld-wrapper.properties b/examples/lib/bld/bld-wrapper.properties
index c139065..095b48c 100644
--- a/examples/lib/bld/bld-wrapper.properties
+++ b/examples/lib/bld/bld-wrapper.properties
@@ -1,7 +1,7 @@
 bld.downloadExtensionJavadoc=false
 bld.downloadExtensionSources=true
 bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.0-SNAPSHOT
-bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS
+bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL,RIFE2_SNAPSHOTS,RIFE2_RELEASES
 bld.downloadLocation=
 bld.sourceDirectories=
 bld.version=1.7.5
diff --git a/examples/src/bld/java/com/example/ExampleBuild.java b/examples/src/bld/java/com/example/ExampleBuild.java
index 6531a3b..ecd8beb 100644
--- a/examples/src/bld/java/com/example/ExampleBuild.java
+++ b/examples/src/bld/java/com/example/ExampleBuild.java
@@ -8,6 +8,7 @@ import rife.bld.extension.dokka.LoggingLevel;
 import rife.bld.operations.exceptions.ExitStatusException;
 
 import java.io.IOException;
+import java.nio.file.Path;
 import java.util.List;
 import java.util.logging.ConsoleHandler;
 import java.util.logging.Level;
@@ -54,6 +55,34 @@ public class ExampleBuild extends BaseProject {
                 .execute();
     }
 
+    @BuildCommand(value = "dokka-gfm", summary = "Generates documentation in GitHub flavored markdown format")
+    public void dokkaGfm() throws ExitStatusException, IOException, InterruptedException {
+        new DokkaOperation()
+                .fromProject(this)
+                .loggingLevel(LoggingLevel.INFO)
+                .pluginsClasspath(true)
+                .pluginsClasspath("lib/bld/dokka-base-1.9.10.jar",
+                        "lib/bld/analysis-kotlin-descriptors-1.9.10.jar",
+                        "lib/bld/gfm-plugin-1.9.10.jar",
+                        "lib/bld/freemarker-2.3.31.jar")
+                .outputDir(Path.of(buildDirectory().getAbsolutePath(), "dokka", "gfm").toFile())
+                .execute();
+    }
+
+    @BuildCommand(value = "dokka-html", summary = "Generates documentation in HTML format")
+    public void dokkaHtml() throws ExitStatusException, IOException, InterruptedException {
+        new DokkaOperation()
+                .fromProject(this)
+                .loggingLevel(LoggingLevel.INFO)
+                .pluginsClasspath(true)
+                .pluginsClasspath("lib/bld/dokka-base-1.9.10.jar",
+                        "lib/bld/analysis-kotlin-descriptors-1.9.10.jar",
+                        "lib/bld/kotlinx-html-jvm-0.7.5.jar",
+                        "lib/bld/freemarker-2.3.31.jar")
+                .outputDir(Path.of(buildDirectory().getAbsolutePath(), "dokka", "html").toFile())
+                .execute();
+    }
+
     @BuildCommand(summary = "Generates Javadoc for the project")
     public void javadoc() throws ExitStatusException, IOException, InterruptedException {
         new DokkaOperation()
diff --git a/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java b/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java
index d70aed3..bc47baf 100644
--- a/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java
+++ b/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java
@@ -47,6 +47,7 @@ public class CompileKotlinOperationBuild extends Project {
                 .include(dependency("org.jetbrains.dokka", "dokka-base", dokka))
                 .include(dependency("org.jetbrains.dokka", "analysis-kotlin-descriptors", dokka))
                 .include(dependency("org.jetbrains.dokka", "javadoc-plugin", dokka))
+                .include(dependency("org.jetbrains.dokka", "gfm-plugin", dokka))
                 .include(dependency("com.uwyn.rife2", "bld", version(1, 7, 5)));
         scope(test)
                 .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 0)))
diff --git a/src/main/java/rife/bld/extension/dokka/DokkaOperation.java b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
index 17723d8..9daf5d2 100644
--- a/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
+++ b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
@@ -426,28 +426,6 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
-    /**
-     * Sets the list of jars with Dokka plugins and their dependencies.
-     *
-     * @param jars one or more jars
-     * @return this operation instance
-     */
-    public DokkaOperation pluginClassPath(String... jars) {
-        pluginsClasspath_.addAll(Arrays.asList(jars));
-        return this;
-    }
-
-    /**
-     * Sets the list of jars with Dokka plugins and their dependencies.
-     *
-     * @param jars the list of jars
-     * @return this operation instance
-     */
-    public DokkaOperation pluginClassPath(Collection<String> jars) {
-        pluginsClasspath_.addAll(jars);
-        return this;
-    }
-
     /**
      * Sets the configuration for Dokka plugins.
      *
@@ -472,6 +450,41 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
+    /**
+     * Sets the list of jars with Dokka plugins and their dependencies.
+     *
+     * @param jars one or more jars
+     * @return this operation instance
+     */
+    public DokkaOperation pluginsClasspath(String... jars) {
+        pluginsClasspath_.addAll(Arrays.asList(jars));
+        return this;
+    }
+
+    /**
+     * Sets the list of jars with Dokka plugins and their dependencies.
+     *
+     * @param jars the list of jars
+     * @return this operation instance
+     */
+    public DokkaOperation pluginsClasspath(Collection<String> jars) {
+        pluginsClasspath_.addAll(jars);
+        return this;
+    }
+
+    /**
+     * Clears the list of Dokka plugins.
+     *
+     * @param clear set to clear the list
+     * @return this operation instance
+     */
+    public DokkaOperation pluginsClasspath(boolean clear) {
+        if (clear) {
+            pluginsClasspath_.clear();
+        }
+        return this;
+    }
+
     /**
      * Sets the configurations for a source set.
      *
diff --git a/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java b/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
index f067a01..f37b9a5 100644
--- a/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
+++ b/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
@@ -43,8 +43,8 @@ class DokkaOperationTest {
                 .includes("file1", "file2")
                 .pluginConfiguration("name", "\"json\"")
                 .pluginConfiguration(Map.of("\"name2\"", "json2"))
-                .pluginClassPath("path1", "path2")
-                .pluginClassPath(List.of("path3", "path4"))
+                .pluginsClasspath("path1", "path2")
+                .pluginsClasspath(List.of("path3", "path4"))
                 .delayTemplateSubstitution(true)
                 .failOnWarning(true)
                 .loggingLevel(LoggingLevel.DEBUG)
@@ -84,9 +84,9 @@ class DokkaOperationTest {
 
         IntStream.range(0, args.size()).forEach(i -> {
             if (args.get(i).contains(".jar;")) {
-               var jars =  args.get(i).split(";");
+                var jars = args.get(i).split(";");
                 Arrays.stream(jars).forEach(jar -> assertThat(matches.get(i)).contains(jar));
-            } else{
+            } else {
                 assertThat(args.get(i)).isEqualTo(matches.get(i));
             }
         });