Added method to reset the Dokka plugins

Added examples for generating documenation in HTML and markdown formats
rife2 · Nov 6, 2023 · 84f1421 · 84f1421
1 parent c59a085
commit 84f1421
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 24 deletions.
diff --git 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
diff --git 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
@@ -8,6 +8,7 @@
 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 void compile() throws IOException {
                 .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
@@ -47,6 +47,7 @@ public CompileKotlinOperationBuild() {
                 .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
@@ -427,48 +427,61 @@ public DokkaOperation outputDir(File outputDir) {
     }
 
     /**
-     * Sets the list of jars with Dokka plugins and their dependencies.
+     * Sets the configuration for Dokka plugins.
      *
-     * @param jars one or more jars
+     * @param name              The fully-qualified plugin name
+     * @param jsonConfiguration The plugin JSON configuration
      * @return this operation instance
      */
-    public DokkaOperation pluginClassPath(String... jars) {
-        pluginsClasspath_.addAll(Arrays.asList(jars));
+    public DokkaOperation pluginConfiguration(String name, String jsonConfiguration) {
+        pluginConfiguration_.put(name, jsonConfiguration);
+        return this;
+    }
+
+    /**
+     * Sets the configuration for Dokka plugins.
+     *
+     * @param pluginConfiguration the map of configurations
+     * @return this operation instance
+     * @see #pluginConfiguration(String, String)
+     */
+    public DokkaOperation pluginConfiguration(Map<String, String> pluginConfiguration) {
+        pluginConfiguration_.putAll(pluginConfiguration);
         return this;
     }
 
     /**
      * Sets the list of jars with Dokka plugins and their dependencies.
      *
-     * @param jars the list of jars
+     * @param jars one or more jars
      * @return this operation instance
      */
-    public DokkaOperation pluginClassPath(Collection<String> jars) {
-        pluginsClasspath_.addAll(jars);
+    public DokkaOperation pluginsClasspath(String... jars) {
+        pluginsClasspath_.addAll(Arrays.asList(jars));
         return this;
     }
 
     /**
-     * Sets the configuration for Dokka plugins.
+     * Sets the list of jars with Dokka plugins and their dependencies.
      *
-     * @param name              The fully-qualified plugin name
-     * @param jsonConfiguration The plugin JSON configuration
+     * @param jars the list of jars
      * @return this operation instance
      */
-    public DokkaOperation pluginConfiguration(String name, String jsonConfiguration) {
-        pluginConfiguration_.put(name, jsonConfiguration);
+    public DokkaOperation pluginsClasspath(Collection<String> jars) {
+        pluginsClasspath_.addAll(jars);
         return this;
     }
 
     /**
-     * Sets the configuration for Dokka plugins.
+     * Clears the list of Dokka plugins.
      *
-     * @param pluginConfiguration the map of configurations
+     * @param clear set to clear the list
      * @return this operation instance
-     * @see #pluginConfiguration(String, String)
      */
-    public DokkaOperation pluginConfiguration(Map<String, String> pluginConfiguration) {
-        pluginConfiguration_.putAll(pluginConfiguration);
+    public DokkaOperation pluginsClasspath(boolean clear) {
+        if (clear) {
+            pluginsClasspath_.clear();
+        }
         return this;
     }
 

diff --git a/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java b/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
@@ -43,8 +43,8 @@ void executeConstructProcessCommandListTest() {
                 .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 @@ void executeConstructProcessCommandListTest() {
 
         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));
             }
         });