Improve Dokka plugin parameters DSL (#36)

* dokka plugin parameters DSL - remove the old DokkaPluginConfigurationSpec, replace with a base plugin config class, DokkaPluginParametersBaseSpec - create specific config classes for the Versioning and HTML plugins. - create a plugin config class for dynamically creating plugin config.
adamko-dev · Mar 16, 2023 · 5e3cbb3 · 5e3cbb3
1 parent 17f2c7e
commit 5e3cbb3
Show file tree

Hide file tree

Showing 18 changed files with 779 additions and 163 deletions.
diff --git a/examples/custom-format-example/dokkatoo/build.gradle.kts b/examples/custom-format-example/dokkatoo/build.gradle.kts
@@ -1,27 +1,16 @@
+import dev.adamko.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters
+
 plugins {
   kotlin("jvm") version "1.7.20"
   id("dev.adamko.dokkatoo") version "0.0.5-SNAPSHOT"
 }
 
 dokkatoo {
   moduleName.set("customFormat-example")
-  dokkatooPublications.named("html") {
-//  dokkatooPublications.configureEach {
-    pluginsConfiguration.create("org.jetbrains.dokka.base.DokkaBase") {
-      /** Custom format adds a custom logo */
-      values.set(
-        """
-          {
-            "customStyleSheets": [
-              "${file("logo-styles.css").invariantSeparatorsPath}"
-            ],
-            "customAssets": [
-              "${file("ktor-logo.png").invariantSeparatorsPath}"
-            ],
-            "footerMessage": "(c) Custom Format Dokka example"
-          }
-        """.trimIndent()
-      )
-    }
+  pluginsConfiguration.named<DokkaHtmlPluginParameters>("html") {
+    // Custom format adds a custom logo
+    customStyleSheets.from("logo-styles.css")
+    customAssets.from("ktor-logo.png")
+    footerMessage.set("(c) Custom Format Dokka example")
   }
 }
diff --git a/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/build.gradle.kts b/modules/dokkatoo-plugin-integration-tests/projects/it-basic/dokkatoo/build.gradle.kts
@@ -1,4 +1,5 @@
 import dev.adamko.dokkatoo.dokka.parameters.VisibilityModifier
+import dev.adamko.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters
 
 plugins {
   kotlin("jvm") version "1.7.20"
@@ -39,23 +40,19 @@ dokkatoo {
       )
     }
   }
+
+  pluginsConfiguration.named<DokkaHtmlPluginParameters>("html") {
+    customStyleSheets.from(
+      "./customResources/logo-styles.css",
+      "./customResources/custom-style-to-add.css",
+    )
+    customAssets.from(
+      "./customResources/custom-resource.svg",
+    )
+  }
+
   dokkatooPublications.configureEach {
     suppressObviousFunctions.set(true)
-    pluginsConfiguration.create("org.jetbrains.dokka.base.DokkaBase") {
-      values.set(
-        """
-          { 
-            "customStyleSheets": [
-              "${file("./customResources/logo-styles.css").invariantSeparatorsPath}", 
-              "${file("./customResources/custom-style-to-add.css").invariantSeparatorsPath}"
-            ], 
-            "customAssets": [
-              "${file("./customResources/custom-resource.svg").invariantSeparatorsPath}"
-            ] 
-          }
-        """.trimIndent()
-      )
-    }
     suppressObviousFunctions.set(false)
   }
 }

diff --git a/modules/dokkatoo-plugin/api/dokkatoo-plugin.api b/modules/dokkatoo-plugin/api/dokkatoo-plugin.api
@@ -16,11 +16,12 @@ public abstract class dev/adamko/dokkatoo/DokkatooExtension : java/io/Serializab
 	public abstract fun getDokkatooConfigurationsDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkatooModuleDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkatooPublicationDirectory ()Lorg/gradle/api/file/DirectoryProperty;
-	public abstract fun getDokkatooPublications ()Lorg/gradle/api/NamedDomainObjectContainer;
+	public final fun getDokkatooPublications ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public abstract fun getDokkatooSourceSets ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public abstract fun getModuleName ()Lorg/gradle/api/provider/Property;
 	public abstract fun getModulePath ()Lorg/gradle/api/provider/Property;
 	public abstract fun getModuleVersion ()Lorg/gradle/api/provider/Property;
+	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
 	public abstract fun getSourceSetScopeDefault ()Lorg/gradle/api/provider/Property;
 }
 
@@ -51,7 +52,7 @@ public abstract class dev/adamko/dokkatoo/dokka/DokkaPublication : java/io/Seria
 	public abstract fun getOfflineMode ()Lorg/gradle/api/provider/Property;
 	public abstract fun getOutputDir ()Lorg/gradle/api/file/DirectoryProperty;
 	protected final fun getOutputDirPath ()Lorg/gradle/api/provider/Provider;
-	public abstract fun getPluginsConfiguration ()Lorg/gradle/api/NamedDomainObjectContainer;
+	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
 	public abstract fun getSuppressInheritedMembers ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressObviousFunctions ()Lorg/gradle/api/provider/Property;
 }
@@ -88,21 +89,6 @@ public final class dev/adamko/dokkatoo/dokka/parameters/DokkaParametersKxs$$seri
 	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
 }
 
-public abstract class dev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec : dev/adamko/dokkatoo/dokka/parameters/DokkaParameterBuilder, java/io/Serializable, org/gradle/api/Named {
-	public synthetic fun build ()Ljava/lang/Object;
-	public fun getName ()Ljava/lang/String;
-	public final fun getPluginFqn ()Ljava/lang/String;
-	public abstract fun getSerializationFormat ()Lorg/gradle/api/provider/Property;
-	public abstract fun getValues ()Lorg/gradle/api/provider/Property;
-}
-
-public final class dev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec$EncodedFormat : java/lang/Enum {
-	public static final field JSON Ldev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec$EncodedFormat;
-	public static final field XML Ldev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec$EncodedFormat;
-	public static fun valueOf (Ljava/lang/String;)Ldev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec$EncodedFormat;
-	public static fun values ()[Ldev/adamko/dokkatoo/dokka/parameters/DokkaPluginConfigurationSpec$EncodedFormat;
-}
-
 public abstract class dev/adamko/dokkatoo/dokka/parameters/DokkaSourceLinkSpec : dev/adamko/dokkatoo/dokka/parameters/DokkaParameterBuilder, java/io/Serializable {
 	public synthetic fun build ()Ljava/lang/Object;
 	public abstract fun getLocalDirectory ()Lorg/gradle/api/file/DirectoryProperty;
@@ -172,6 +158,124 @@ public final class dev/adamko/dokkatoo/dokka/parameters/VisibilityModifier : jav
 public final class dev/adamko/dokkatoo/dokka/parameters/VisibilityModifier$Companion {
 }
 
+public abstract class dev/adamko/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters : dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec {
+	public static final field Companion Ldev/adamko/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters$Companion;
+	public static final field DOKKA_HTML_PARAMETERS_NAME Ljava/lang/String;
+	public static final field DOKKA_HTML_PLUGIN_FQN Ljava/lang/String;
+	public abstract fun getCustomAssets ()Lorg/gradle/api/file/ConfigurableFileCollection;
+	public abstract fun getCustomStyleSheets ()Lorg/gradle/api/file/ConfigurableFileCollection;
+	public abstract fun getFooterMessage ()Lorg/gradle/api/provider/Property;
+	public abstract fun getMergeImplicitExpectActualDeclarations ()Lorg/gradle/api/provider/Property;
+	public abstract fun getSeparateInheritedMembers ()Lorg/gradle/api/provider/Property;
+	public abstract fun getTemplatesDir ()Lorg/gradle/api/file/DirectoryProperty;
+	public fun jsonEncode ()Ljava/lang/String;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters$Companion {
+}
+
+public abstract class dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec : dev/adamko/dokkatoo/dokka/parameters/DokkaParameterBuilder, java/io/Serializable, org/gradle/api/Named {
+	public fun build ()Ldev/adamko/dokkatoo/dokka/parameters/DokkaParametersKxs$PluginConfigurationKxs;
+	public synthetic fun build ()Ljava/lang/Object;
+	public fun getName ()Ljava/lang/String;
+	public fun getPluginFqn ()Ljava/lang/String;
+	public abstract fun jsonEncode ()Ljava/lang/String;
+}
+
+public abstract class dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder : dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec {
+	public static final field Companion Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder$Companion;
+	public fun getPluginFqn ()Ljava/lang/String;
+	public fun jsonEncode ()Ljava/lang/String;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder$Companion {
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilderKt {
+	public static final fun PluginConfigBooleanValue (Lorg/gradle/api/provider/Provider;)Lorg/gradle/api/provider/Provider;
+	public static final fun PluginConfigNumberValue (Lorg/gradle/api/provider/Provider;)Lorg/gradle/api/provider/Provider;
+	public static final fun PluginConfigStringValue (Lorg/gradle/api/provider/Provider;)Lorg/gradle/api/provider/Provider;
+	public static final fun PluginConfigValue (Ljava/lang/Number;)Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$NumberValue;
+	public static final fun PluginConfigValue (Ljava/lang/String;)Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$StringValue;
+	public static final fun PluginConfigValue (Z)Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$BooleanValue;
+	public static final fun add (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Ljava/lang/Number;)V
+	public static final fun add (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Ljava/lang/String;)V
+	public static final fun add (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Z)V
+	public static final fun addBoolean (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Lorg/gradle/api/provider/Provider;)V
+	public static final fun addNumber (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Lorg/gradle/api/provider/Provider;)V
+	public static final fun addString (Ldev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values;Lorg/gradle/api/provider/Provider;)V
+	public static final fun booleanProperty (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Lorg/gradle/api/provider/Provider;)V
+	public static final fun files (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public static final fun numberProperty (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Lorg/gradle/api/provider/Provider;)V
+	public static final fun pluginParameters (Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public static final fun properties (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public static final fun property (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Ljava/lang/Number;)V
+	public static final fun property (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Ljava/lang/String;)V
+	public static final fun property (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Z)V
+	public static final fun stringProperty (Ldev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder;Ljava/lang/String;Lorg/gradle/api/provider/Provider;)V
+}
+
+public abstract class dev/adamko/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters : dev/adamko/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec {
+	public static final field Companion Ldev/adamko/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters$Companion;
+	public static final field DOKKA_VERSIONING_PLUGIN_FQN Ljava/lang/String;
+	public static final field DOKKA_VERSIONING_PLUGIN_PARAMETERS_NAME Ljava/lang/String;
+	public abstract fun getOlderVersions ()Lorg/gradle/api/file/ConfigurableFileCollection;
+	public abstract fun getOlderVersionsDir ()Lorg/gradle/api/file/DirectoryProperty;
+	public abstract fun getRenderVersionsNavigationOnAllPages ()Lorg/gradle/api/provider/Property;
+	public abstract fun getVersion ()Lorg/gradle/api/provider/Property;
+	public abstract fun getVersionsOrdering ()Lorg/gradle/api/provider/ListProperty;
+	public fun jsonEncode ()Ljava/lang/String;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters$Companion {
+}
+
+public abstract class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$DirectoryValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+	public fun <init> (Lorg/gradle/api/file/DirectoryProperty;)V
+	public final fun getDirectory ()Lorg/gradle/api/file/DirectoryProperty;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$FileValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+	public fun <init> (Lorg/gradle/api/file/RegularFileProperty;)V
+	public final fun getFile ()Lorg/gradle/api/file/RegularFileProperty;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$FilesValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+	public fun <init> (Lorg/gradle/api/file/ConfigurableFileCollection;)V
+	public final fun getFiles ()Lorg/gradle/api/file/ConfigurableFileCollection;
+}
+
+public abstract class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$BooleanValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive {
+	public fun <init> (Z)V
+	public final fun getBoolean ()Z
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$NumberValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive {
+	public fun <init> (Ljava/lang/Number;)V
+	public final fun getNumber ()Ljava/lang/Number;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive$StringValue : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Primitive {
+	public fun <init> (Ljava/lang/String;)V
+	public final fun getString ()Ljava/lang/String;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Properties : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+	public fun <init> (Lorg/gradle/api/provider/MapProperty;)V
+	public final fun getValues ()Lorg/gradle/api/provider/MapProperty;
+}
+
+public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values : dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue {
+	public fun <init> (Lorg/gradle/api/provider/ListProperty;)V
+	public final fun getValues ()Lorg/gradle/api/provider/ListProperty;
+}
+
 public abstract class dev/adamko/dokkatoo/formats/DokkatooFormatPlugin : org/gradle/api/Plugin {
 	public static final field Companion Ldev/adamko/dokkatoo/formats/DokkatooFormatPlugin$Companion;
 	public fun <init> (Ljava/lang/String;)V
@@ -186,6 +290,7 @@ public abstract class dev/adamko/dokkatoo/formats/DokkatooGfmPlugin : dev/adamko
 }
 
 public abstract class dev/adamko/dokkatoo/formats/DokkatooHtmlPlugin : dev/adamko/dokkatoo/formats/DokkatooFormatPlugin {
+	public fun configure (Ldev/adamko/dokkatoo/formats/DokkatooFormatPlugin$DokkatooFormatPluginContext;)V
 }
 
 public abstract class dev/adamko/dokkatoo/formats/DokkatooJavadocPlugin : dev/adamko/dokkatoo/formats/DokkatooFormatPlugin {
@@ -240,8 +345,7 @@ public abstract class dev/adamko/dokkatoo/tasks/DokkatooPrepareParametersTask :
 	public final fun getOutputDir ()Lorg/gradle/api/file/DirectoryProperty;
 	protected final fun getOutputDirPath ()Lorg/gradle/api/provider/Provider;
 	public abstract fun getPluginsClasspath ()Lorg/gradle/api/file/ConfigurableFileCollection;
-	public abstract fun getPluginsConfiguration ()Lorg/gradle/api/NamedDomainObjectContainer;
-	public abstract fun getPluginsMapConfiguration ()Lorg/gradle/api/provider/MapProperty;
+	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
 	public abstract fun getPublicationEnabled ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressInheritedMembers ()Lorg/gradle/api/provider/Property;
 	public abstract fun getSuppressObviousFunctions ()Lorg/gradle/api/provider/Property;

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt
@@ -4,7 +4,6 @@ import dev.adamko.dokkatoo.distibutions.DokkatooConfigurationAttributes
 import dev.adamko.dokkatoo.distibutions.DokkatooConfigurationAttributes.Companion.DOKKATOO_BASE_ATTRIBUTE
 import dev.adamko.dokkatoo.distibutions.DokkatooConfigurationAttributes.Companion.DOKKATOO_CATEGORY_ATTRIBUTE
 import dev.adamko.dokkatoo.distibutions.DokkatooConfigurationAttributes.Companion.DOKKA_FORMAT_ATTRIBUTE
-import dev.adamko.dokkatoo.dokka.parameters.DokkaPluginConfigurationSpec.EncodedFormat
 import dev.adamko.dokkatoo.dokka.parameters.VisibilityModifier
 import dev.adamko.dokkatoo.formats.*
 import dev.adamko.dokkatoo.internal.*
@@ -130,7 +129,6 @@ constructor(
   ) {
     dokkatooExtension.dokkatooPublications.all {
       enabled.convention(true)
-
       cacheRoot.convention(dokkatooExtension.dokkatooCacheDirectory)
       delayTemplateSubstitution.convention(false)
       failOnWarning.convention(false)
@@ -141,10 +139,6 @@ constructor(
       outputDir.convention(dokkatooExtension.dokkatooPublicationDirectory)
       suppressInheritedMembers.convention(false)
       suppressObviousFunctions.convention(true)
-
-      pluginsConfiguration.configureEach {
-        serializationFormat.convention(EncodedFormat.JSON)
-      }
     }
   }
 

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooExtension.kt b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooExtension.kt
@@ -2,20 +2,25 @@ package dev.adamko.dokkatoo
 
 import dev.adamko.dokkatoo.dokka.DokkaPublication
 import dev.adamko.dokkatoo.dokka.parameters.DokkaSourceSetSpec
+import dev.adamko.dokkatoo.dokka.plugins.DokkaPluginParametersBaseSpec
+import dev.adamko.dokkatoo.internal.DokkaPluginParametersContainer
 import dev.adamko.dokkatoo.internal.DokkatooInternalApi
 import java.io.Serializable
 import org.gradle.api.NamedDomainObjectContainer
 import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.model.ObjectFactory
 import org.gradle.api.plugins.ExtensionAware
 import org.gradle.api.provider.Property
+import org.gradle.kotlin.dsl.*
 
 /**
  * Configure the behaviour of the [DokkatooBasePlugin].
  */
 abstract class DokkatooExtension
 @DokkatooInternalApi
-constructor() :
-  ExtensionAware, Serializable {
+constructor(
+  objects: ObjectFactory,
+) : ExtensionAware, Serializable {
 
   /** Directory into which [DokkaPublication]s will be produced */
   abstract val dokkatooPublicationDirectory: DirectoryProperty
@@ -46,7 +51,10 @@ constructor() :
    *
    * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated.
    */
-  abstract val dokkatooPublications: NamedDomainObjectContainer<DokkaPublication>
+  val dokkatooPublications: NamedDomainObjectContainer<DokkaPublication> =
+    objects.domainObjectContainer(DokkaPublication::class) { named ->
+      objects.newInstance(named, pluginsConfiguration)
+    }
 
   /**
    * Dokka Source Sets describe the source code that should be included in a Dokka Publication.
@@ -78,6 +86,14 @@ constructor() :
    */
   abstract val dokkatooSourceSets: NamedDomainObjectContainer<DokkaSourceSetSpec>
 
+  /**
+   * Dokka Plugin are used to configure the way Dokka generates a format.
+   * Some plugins can be configured via parameters, and those parameters are stored in this
+   * container.
+   */
+  val pluginsConfiguration: DokkaPluginParametersContainer =
+    objects.polymorphicDomainObjectContainer(DokkaPluginParametersBaseSpec::class)
+
   interface Versions {
 
     /** Default version used for Dokka dependencies */