Add ability to specify older versions as a list of files (#1890)

* Specify older versions as a list of files, add option to use directory

* Allow specifying older version directory as well

* Cleanup

* Update API export

* Update versioning docs

2 files changed, 18 insertions, 9 deletions

diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt
index e01f3419..f5c69cf4 100644
--- a/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt
+++ b/plugins/versioning/src/main/kotlin/versioning/VersioningConfiguration.kt
@@ -6,14 +6,23 @@ import java.io.File
 
 data class VersioningConfiguration(
     var olderVersionsDir: File? = defaultOlderVersionsDir,
+    var olderVersions: List<File>? = defaultOlderVersions,
     var versionsOrdering: List<String>? = defaultVersionsOrdering,
     var version: String? = defaultVersion,
 ) : ConfigurableBlock {
     internal fun versionFromConfigurationOrModule(dokkaContext: DokkaContext): String =
         version ?: dokkaContext.configuration.moduleVersion ?: "1.0"
 
+    internal fun allOlderVersions(): List<File> {
+        if (olderVersionsDir != null)
+            assert(olderVersionsDir!!.isDirectory) { "Supplied previous version $olderVersionsDir is not a directory!" }
+
+        return olderVersionsDir?.listFiles()?.toList().orEmpty() + olderVersions.orEmpty()
+    }
+
     companion object {
         val defaultOlderVersionsDir: File? = null
+        val defaultOlderVersions: List<File>? = null
         val defaultVersionsOrdering: List<String>? = null
         val defaultVersion = null
     }
diff --git a/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt b/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt
index 699c87e6..41700282 100644
--- a/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt
+++ b/plugins/versioning/src/main/kotlin/versioning/VersioningHandler.kt
@@ -3,7 +3,10 @@ package org.jetbrains.dokka.versioning
 import com.fasterxml.jackson.annotation.JsonProperty
 import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.module.kotlin.readValue
-import kotlinx.coroutines.*
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 import org.jetbrains.dokka.plugability.DokkaContext
 import org.jetbrains.dokka.plugability.configuration
 import org.jetbrains.dokka.plugability.plugin
@@ -40,9 +43,7 @@ class DefaultVersioningHandler(val context: DokkaContext) : VersioningHandler {
         configuration?.let { versionsConfiguration ->
             versions =
                 mapOf(versionsConfiguration.versionFromConfigurationOrModule(context) to context.configuration.outputDir)
-            versionsConfiguration.olderVersionsDir?.let {
-                handlePreviousVersions(it, context.configuration.outputDir)
-            }
+            handlePreviousVersions(versionsConfiguration.allOlderVersions(), context.configuration.outputDir)
             mapper.writeValue(
                 context.configuration.outputDir.resolve(VERSIONS_FILE),
                 Version(versionsConfiguration.versionFromConfigurationOrModule(context))
@@ -50,9 +51,8 @@ class DefaultVersioningHandler(val context: DokkaContext) : VersioningHandler {
         }
     }
 
-    private fun handlePreviousVersions(olderVersionDir: File, output: File): Map<String, File> {
-        assert(olderVersionDir.isDirectory) { "Supplied previous version $olderVersionDir is not a directory!" }
-        return versionsWithOriginDir(olderVersionDir)
+    private fun handlePreviousVersions(olderVersions: List<File>, output: File): Map<String, File> {
+        return versionsFrom(olderVersions)
             .also { fetched ->
                 versions = versions + fetched.map { (key, _) ->
                     key to output.resolve(OLDER_VERSIONS_DIR).resolve(key)
@@ -61,8 +61,8 @@ class DefaultVersioningHandler(val context: DokkaContext) : VersioningHandler {
             .onEach { (version, path) -> copyVersion(version, path, output) }.toMap()
     }
 
-    private fun versionsWithOriginDir(olderVersionRootDir: File) =
-        olderVersionRootDir.listFiles().orEmpty().mapNotNull { versionDir ->
+    private fun versionsFrom(olderVersions: List<File>) =
+        olderVersions.mapNotNull { versionDir ->
             versionDir.listFiles { _, name -> name == VERSIONS_FILE }?.firstOrNull()?.let { file ->
                 val versionsContent = mapper.readValue<Version>(file)
                 Pair(versionsContent.version, versionDir)