Stabilize ExternalDocumentableProvider (#3312)

4 files changed, 33 insertions, 0 deletions

diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
index f729838d..714ee16a 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
@@ -5,6 +5,7 @@
 package org.jetbrains.dokka.analysis.test.api.analysis
 
 import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
+import org.jetbrains.dokka.analysis.kotlin.documentable.ExternalDocumentableProvider
 import org.jetbrains.dokka.analysis.kotlin.internal.ModuleAndPackageDocumentationReader
 import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreator
 
@@ -16,5 +17,6 @@ import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreat
  */
 class TestAnalysisServices(
     val sampleAnalysisEnvironmentCreator: SampleAnalysisEnvironmentCreator,
+    val externalDocumentableProvider: ExternalDocumentableProvider,
     val moduleAndPackageDocumentationReader: ModuleAndPackageDocumentationReader
 )
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
index 674c6d47..7a410d7d 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
@@ -228,6 +228,7 @@ internal object TestProjectAnalyzer {
         val internalAnalysisPlugin = context.plugin<InternalKotlinAnalysisPlugin>()
         return TestAnalysisServices(
             sampleAnalysisEnvironmentCreator = publicAnalysisPlugin.querySingle { sampleAnalysisEnvironmentCreator },
+            externalDocumentableProvider = publicAnalysisPlugin.querySingle { externalDocumentableProvider },
             moduleAndPackageDocumentationReader = internalAnalysisPlugin.querySingle {
                 moduleAndPackageDocumentationReader
             }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt
index b6563fb7..fc3499ea 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/configuration/TestDokkaConfigurationBuilder.kt
@@ -5,6 +5,7 @@
 package org.jetbrains.dokka.analysis.test.api.configuration
 
 import org.jetbrains.dokka.analysis.test.api.TestProject
+import org.jetbrains.dokka.analysis.test.api.util.getResourceAbsolutePath
 import org.jetbrains.dokka.analysis.test.api.util.AnalysisTestDslMarker
 
 /**
@@ -66,6 +67,8 @@ abstract class BaseTestDokkaSourceSetBuilder {
     /**
      * JARs **additional** to the default classpath.
      *
+     * You can put test JARs inside `src/resources`, and then get it via [getResourceAbsolutePath].
+     *
      * @see TestDokkaSourceSet.classpath
      */
     open var additionalClasspath: Set<String> = emptySet()
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/FileUtils.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/FileUtils.kt
index 779add8d..afa3e84a 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/FileUtils.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/FileUtils.kt
@@ -39,3 +39,30 @@ internal fun <T> withTempDirectory(logger: DokkaLogger? = null, block: (tempDire
         logger?.debug("Deleted temporary directory $tempDir")
     }
 }
+
+/**
+ * Finds a resource by [resourcePath], and returns its absolute path.
+ *
+ * A resource is usually a file found in the `resources` directory of the project.
+ *
+ * For example, if you have a file `project/src/main/resources/jars/kotlinx-cli-jvm-0.3.6.jar`,
+ * you should be able to get it by calling this function as
+ * `getResourceAbsolutePath("jars/kotlinx-cli-jvm-0.3.6.jar")`.
+ *
+ * @throws IllegalArgumentException if the resource cannot be found or does not exist
+ * @return an absolute path to the resource, such as `/home/user/projects/dokka/../MyFile.md`
+ */
+fun getResourceAbsolutePath(resourcePath: String): String {
+    val resourceFile = getResourceFile(resourcePath)
+    require(resourceFile.exists()) {
+        "Resource file does not exist: $resourcePath"
+    }
+    return resourceFile.absolutePath
+}
+
+private fun getResourceFile(resourcePath: String): File {
+    val resource = object {}.javaClass.classLoader.getResource(resourcePath)?.file
+        ?: throw IllegalArgumentException("Resource not found: $resourcePath")
+
+    return File(resource)
+}