Rename dokkaPublicationDirectory to basePublicationsDirectory (#3876

) * Rename `dokkaPublicationDirectory` to `basePublicationsDirectory` * Update output dir docs * update api dump * deprecate level ERROR * update outputDirectory v1 config
Kotlin · Oct 22, 2024 · 0ddbc9c · 0ddbc9c
1 parent 1955c11
commit 0ddbc9c
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 13 deletions.
diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md
@@ -209,25 +209,23 @@ options according to your project setup:
     customAssets.from("example.png", "example2.png")
     ```
 
-* **Output directory:** Use the `dokka {}` block to specify a single output directory for all Dokka-generated documentation.
+* **Output directory:** Use the `dokka {}` block to specify the output directory for generated Dokka documentation.
 
     Previous configuration:
 
     ```kotlin
-    tasks.dokkaHtml{
-        dokkaSourceSets {
-            configureEach {
-                outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
-            }
-        }
+    tasks.dokkaHtml {
+        outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
     }
     ```
 
     New configuration:
 
     ```kotlin
     dokka {
-        dokkaPublicationDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+        dokkaPublications.html {
+            outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+        }
     }
     ```
 

diff --git a/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api b/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api
@@ -79,11 +79,12 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public static synthetic fun ClassLoaderIsolation$default (Lorg/jetbrains/dokka/gradle/DokkaExtension;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$ClassLoader;
 	public final fun ProcessIsolation (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
 	public static synthetic fun ProcessIsolation$default (Lorg/jetbrains/dokka/gradle/DokkaExtension;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
+	public abstract fun getBasePublicationsDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkaCacheDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkaEngineVersion ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaGeneratorIsolation ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaModuleDirectory ()Lorg/gradle/api/file/DirectoryProperty;
-	public abstract fun getDokkaPublicationDirectory ()Lorg/gradle/api/file/DirectoryProperty;
+	public final fun getDokkaPublicationDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public final fun getDokkaPublications ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public final fun getDokkaSourceSets ()Lorg/gradle/api/NamedDomainObjectContainer;
 	public abstract fun getModuleName ()Lorg/gradle/api/provider/Property;

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
@@ -100,7 +100,7 @@ constructor(
             )
 
             sourceSetScopeDefault.convention(project.path)
-            dokkaPublicationDirectory.convention(layout.buildDirectory.dir("dokka"))
+            basePublicationsDirectory.convention(layout.buildDirectory.dir("dokka"))
             dokkaModuleDirectory.convention(layout.buildDirectory.dir("dokka-module"))
 //            @Suppress("DEPRECATION")
 //            dokkaConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
@@ -157,7 +157,7 @@ constructor(
             moduleName.convention(dokkaExtension.moduleName)
             moduleVersion.convention(dokkaExtension.moduleVersion)
             offlineMode.convention(false)
-            outputDirectory.convention(dokkaExtension.dokkaPublicationDirectory.dir(formatName))
+            outputDirectory.convention(dokkaExtension.basePublicationsDirectory.dir(formatName))
             moduleOutputDirectory.convention(dokkaExtension.dokkaModuleDirectory.dir(formatName))
             suppressInheritedMembers.convention(
                 @Suppress("DEPRECATION")

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -21,6 +21,7 @@ import org.jetbrains.dokka.gradle.workers.ClassLoaderIsolation
 import org.jetbrains.dokka.gradle.workers.ProcessIsolation
 import org.jetbrains.dokka.gradle.workers.WorkerIsolation
 import java.io.Serializable
+import kotlin.DeprecationLevel.ERROR
 
 /**
  * Configure the behaviour of the [DokkaBasePlugin].
@@ -32,8 +33,23 @@ constructor(
     internal val baseDependencyManager: BaseDependencyManager,
 ) : ExtensionAware, Serializable {
 
-    /** Directory into which [DokkaPublication]s will be produced */
-    abstract val dokkaPublicationDirectory: DirectoryProperty
+    /**
+     * Base directory into which all [DokkaPublication]s will be produced.
+     * By default, Dokka will generate all [DokkaPublication]s into a subdirectory inside [basePublicationsDirectory].
+     *
+     * To configure the output for a specific Publication, instead use [DokkaPublication.outputDirectory].
+     *
+     * #### Example
+     *
+     * Here we configure the output directory to be `./build/dokka-docs/`.
+     * Dokka will produce the HTML Publication into `./build/dokka-docs/html/`
+     * ```
+     * dokka {
+     *     basePublicationsDirectory.set(layout.buildDirectory.dir("dokka-docs"))
+     * }
+     * ```
+     */
+    abstract val basePublicationsDirectory: DirectoryProperty
 
     /**
      * Directory into which Dokka Modules will be produced.
@@ -180,6 +196,17 @@ constructor(
 
 
     //region deprecated properties
+    /** Deprecated. Use [basePublicationsDirectory] instead. */
+    // Deprecated in 2.0.0-Beta. Remove when Dokka 2.0.0 is released.
+    @Deprecated(
+        "Renamed to basePublicationsDirectory",
+        ReplaceWith("basePublicationsDirectory"),
+        level = ERROR,
+    )
+    @Suppress("unused")
+    val dokkaPublicationDirectory: DirectoryProperty
+        get() = basePublicationsDirectory
+
     /**
      * ```
      * dokka {