automatically add version for Dokka dependencies (#127)

adamko-dev · Dec 16, 2023 · dc6aa5c · dc6aa5c
1 parent f9546e6
commit dc6aa5c
Show file tree

Hide file tree

Showing 8 changed files with 46 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -131,6 +131,10 @@ dokkatoo {
     suppressObviousFunctions.set(true)
     suppressObviousFunctions.set(false)
   }
+  // The default versions that Dokkatoo uses can be overridden:
+  versions {
+    jetbrainsDokka.set("1.9.10")
+  }
 }
 ```
 
@@ -156,12 +160,9 @@ dependencies {
   dokkatoo(projects(":subproject-hello"))
   dokkatoo(projects(":subproject-world"))
 
-  // This is required at the moment, see https://github.com/adamko-dev/dokkatoo/issues/14
-  dokkatooPluginHtml(
-    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
-      "org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion"
-    }
-  )
+  // A dependency on all-modules-page-plugin is required at the moment, see https://github.com/adamko-dev/dokkatoo/issues/14
+  // A version is not required, Dokkatoo will automatically add one.
+  dokkatooPluginHtml("org.jetbrains.dokka:all-modules-page-plugin")
 }
 ```
 

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -27,7 +27,7 @@ idea {
       addAll(
         projectDir.walk().filter { file ->
           excludedDirs.any {
-            file.invariantSeparatorsPath.endsWith(it)
+            file.invariantSeparatorsPath.endsWith("/$it")
           }
         }
       )

diff --git a/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts b/examples/multimodule-example/dokkatoo/parentProject/build.gradle.kts
@@ -6,16 +6,9 @@ plugins {
 dependencies {
   dokkatoo(project(":parentProject:childProjectA"))
   dokkatoo(project(":parentProject:childProjectB"))
-  dokkatooPluginHtml(
-    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
-      "org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion"
-    }
-  )
-  dokkatooPluginHtml(
-    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
-      "org.jetbrains.dokka:templating-plugin:$dokkaVersion"
-    }
-  )
+
+  dokkatooPluginHtml("org.jetbrains.dokka:all-modules-page-plugin")
+  dokkatooPluginHtml("org.jetbrains.dokka:templating-plugin")
 }
 
 dokkatoo {

diff --git a/modules/dokkatoo-plugin/api/dokkatoo-plugin.api b/modules/dokkatoo-plugin/api/dokkatoo-plugin.api
@@ -315,13 +315,17 @@ public final class dev/adamko/dokkatoo/dokka/plugins/PluginConfigValue$Values :
 }
 
 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
 	public synthetic fun apply (Ljava/lang/Object;)V
 	public fun apply (Lorg/gradle/api/Project;)V
 	public fun configure (Ldev/adamko/dokkatoo/formats/DokkatooFormatPlugin$DokkatooFormatPluginContext;)V
 	public final fun getFormatName ()Ljava/lang/String;
 }
 
+public final class dev/adamko/dokkatoo/formats/DokkatooFormatPlugin$Companion {
+}
+
 public final class dev/adamko/dokkatoo/formats/DokkatooFormatTasks$inlined$sam$i$org_gradle_api_Action$0 : org/gradle/api/Action {
 	public fun <init> (Lkotlin/jvm/functions/Function1;)V
 	public final synthetic fun execute (Ljava/lang/Object;)V

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatDependencyContainers.kt b/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatDependencyContainers.kt
@@ -90,7 +90,7 @@ class DokkatooFormatDependencyContainers(
    *
    * Users can add plugins to this dependency.
    *
-   * Should not contain runtime dependencies.
+   * Should not contain runtime dependencies - use [dokkaGeneratorClasspath].
    */
   val dokkaPluginsClasspath: NamedDomainObjectProvider<Configuration> =
     project.configurations.register(dependencyContainerNames.dokkaPluginsClasspath) {

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatPlugin.kt b/modules/dokkatoo-plugin/src/main/kotlin/formats/DokkatooFormatPlugin.kt
@@ -12,6 +12,7 @@ import org.gradle.api.Project
 import org.gradle.api.artifacts.Dependency
 import org.gradle.api.artifacts.dsl.DependencyHandler
 import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.logging.Logging
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.provider.Property
 import org.gradle.api.provider.Provider
@@ -104,6 +105,29 @@ abstract class DokkatooFormatPlugin(
           addDefaultDokkaDependencies()
         }
       }
+
+      if (context.enableVersionAlignment) {
+        //region version alignment
+        listOf(
+          dependencyContainers.dokkaPluginsClasspath,
+          dependencyContainers.dokkaPluginsIntransitiveClasspath,
+          dependencyContainers.dokkaGeneratorClasspath,
+        ).forEach {
+          // Add a version if one is missing, which will allow defining a org.jetbrains.dokka
+          // dependency without a version.
+          // (It would be nice to do this with a virtual-platform, but Gradle is bugged:
+          // https://github.com/gradle/gradle/issues/27435)
+          it.configure {
+            resolutionStrategy.eachDependency {
+              if (requested.group == "org.jetbrains.dokka" && requested.version.isNullOrBlank()) {
+                logger.info("adding version of dokka dependency '$requested'")
+                useVersion(dokkatooExtension.versions.jetbrainsDokka.get())
+              }
+            }
+          }
+        }
+        //endregion
+      }
     }
   }
 
@@ -122,6 +146,7 @@ abstract class DokkatooFormatPlugin(
     private val dependencyContainerNames = DokkatooBasePlugin.DependencyContainerNames(formatName)
 
     var addDefaultDokkaDependencies = true
+    var enableVersionAlignment = true
 
     /** Create a [Dependency] for a Dokka module */
     fun DependencyHandler.dokka(module: String): Provider<Dependency> =
@@ -171,4 +196,7 @@ abstract class DokkatooFormatPlugin(
     }
   }
 
+  companion object {
+    private val logger = Logging.getLogger(DokkatooFormatPlugin::class.java)
+  }
 }
diff --git a/modules/dokkatoo-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt b/modules/dokkatoo-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt
@@ -427,11 +427,7 @@ private fun initDokkatooProject(
       |dependencies {
       |  dokkatoo(project(":subproject-hello"))
       |  dokkatoo(project(":subproject-goodbye"))
-      |  dokkatooPluginHtml(
-      |    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
-      |      "org.jetbrains.dokka:all-modules-page-plugin:${'$'}dokkaVersion"
-      |    }
-      |  )
+      |  dokkatooPluginHtml("org.jetbrains.dokka:all-modules-page-plugin")
       |}
       |
     """.trimMargin()

diff --git a/modules/dokkatoo-plugin/src/testFunctional/kotlin/tasks/LogHtmlPublicationLinkTaskTest.kt b/modules/dokkatoo-plugin/src/testFunctional/kotlin/tasks/LogHtmlPublicationLinkTaskTest.kt
@@ -105,11 +105,7 @@ private fun initDokkatooProject(
       |}
       |
       |dependencies {
-      |  dokkatooPluginHtml(
-      |    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
-      |      "org.jetbrains.dokka:all-modules-page-plugin:${'$'}dokkaVersion"
-      |    }
-      |  )
+      |  dokkatooPluginHtml("org.jetbrains.dokka:all-modules-page-plugin")
       |}
       |
       |tasks.withType<dev.adamko.dokkatoo.tasks.LogHtmlPublicationLinkTask>().configureEach {