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

4 files changed, 37 insertions, 15 deletions

diff --git a/docs/src/doc/docs/user_guide/versioning/versioning.md b/docs/src/doc/docs/user_guide/versioning/versioning.md
index 985fae56..7cb2a783 100644
--- a/docs/src/doc/docs/user_guide/versioning/versioning.md
+++ b/docs/src/doc/docs/user_guide/versioning/versioning.md
@@ -9,6 +9,9 @@ Versioning can be configured using:
 
 * version - a string value representing a version that should be displayed in the dropdown.
 * olderVersionsDir - an optional file that represents the parent directory containing folders with previous Dokka outputs.
+* olderVersions - an optional list of directories, each containing a previous Dokka output.  Used after the contents of 
+  `olderVersionsDir` 
+  (if it's specified).
 * versionsOrdering - an optional list of strings representing the ordering of versions that should be visible. 
   By default, Dokka will try to use semantic versioning to create such ordering.
   
@@ -21,7 +24,7 @@ Configuration object is named `org.jetbrains.dokka.versioning.VersioningConfigur
 
 ### Directory structure required
 
-Versioning plugins requires documentation authors to keep previous outputs in a set structure:
+If you pass previous versions using `olderVersionsDir`, a particular directory structure is required:
 
 ```
 .
@@ -35,6 +38,12 @@ Versioning plugins requires documentation authors to keep previous outputs in a
 
 As can be seen on the diagram, `olderVersionsDir` should be a parent directory of previous output directories.
 
+This can be avoided by manually specifying each past output directory with `olderVersions`, or they can be used 
+together.
+
+`olderVersions` directories need to contain a past Dokka output.  For the above example, you would pass 
+`older_versions_dir/1.4.10, older_versions_dir/1.4.20`.
+
 ### Example
 
 Versioning plugin in gradle can be configured in 2 ways: 
diff --git a/plugins/versioning/api/versioning.api b/plugins/versioning/api/versioning.api
index ba1d91d6..8223579b 100644
--- a/plugins/versioning/api/versioning.api
+++ b/plugins/versioning/api/versioning.api
@@ -56,18 +56,21 @@ public final class org/jetbrains/dokka/versioning/SemVerVersionOrdering : org/je
 public final class org/jetbrains/dokka/versioning/VersioningConfiguration : org/jetbrains/dokka/plugability/ConfigurableBlock {
 	public static final field Companion Lorg/jetbrains/dokka/versioning/VersioningConfiguration$Companion;
 	public fun <init> ()V
-	public fun <init> (Ljava/io/File;Ljava/util/List;Ljava/lang/String;)V
-	public synthetic fun <init> (Ljava/io/File;Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Ljava/io/File;
 	public final fun component2 ()Ljava/util/List;
-	public final fun component3 ()Ljava/lang/String;
-	public final fun copy (Ljava/io/File;Ljava/util/List;Ljava/lang/String;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration;
-	public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/VersioningConfiguration;Ljava/io/File;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration;
+	public final fun component3 ()Ljava/util/List;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun copy (Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration;
+	public static synthetic fun copy$default (Lorg/jetbrains/dokka/versioning/VersioningConfiguration;Ljava/io/File;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/versioning/VersioningConfiguration;
 	public fun equals (Ljava/lang/Object;)Z
+	public final fun getOlderVersions ()Ljava/util/List;
 	public final fun getOlderVersionsDir ()Ljava/io/File;
 	public final fun getVersion ()Ljava/lang/String;
 	public final fun getVersionsOrdering ()Ljava/util/List;
 	public fun hashCode ()I
+	public final fun setOlderVersions (Ljava/util/List;)V
 	public final fun setOlderVersionsDir (Ljava/io/File;)V
 	public final fun setVersion (Ljava/lang/String;)V
 	public final fun setVersionsOrdering (Ljava/util/List;)V
@@ -75,6 +78,7 @@ public final class org/jetbrains/dokka/versioning/VersioningConfiguration : org/
 }
 
 public final class org/jetbrains/dokka/versioning/VersioningConfiguration$Companion {
+	public final fun getDefaultOlderVersions ()Ljava/util/List;
 	public final fun getDefaultOlderVersionsDir ()Ljava/io/File;
 	public final fun getDefaultVersion ()Ljava/lang/Void;
 	public final fun getDefaultVersionsOrdering ()Ljava/util/List;
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)