Add KotlinWebSite plugin to transform samples (#2349)

6 files changed, 250 insertions, 6 deletions

diff --git a/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/build.gradle b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/build.gradle
new file mode 100644
index 00000000..3ab3e09b
--- /dev/null
+++ b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/build.gradle
@@ -0,0 +1,19 @@
+plugins {
+    id 'org.jetbrains.kotlin.jvm'
+}
+description "Dokka Plugin to transform the samples from stdlib"
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "org.jetbrains.dokka:dokka-base:${dokka_it_kotlin_version}"
+    compileOnly "org.jetbrains.dokka:dokka-core:${dokka_it_kotlin_version}"
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile) {
+        kotlinOptions.jvmTarget = "1.8"
+}
+
diff --git a/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/KotlinWebsiteSamplesTransformer.kt b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/KotlinWebsiteSamplesTransformer.kt
new file mode 100644
index 00000000..9d5115cd
--- /dev/null
+++ b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/KotlinWebsiteSamplesTransformer.kt
@@ -0,0 +1,196 @@
+package org.jetbrains.dokka.kotlinlang
+
+import com.intellij.psi.PsiDocumentManager
+import com.intellij.psi.PsiElement
+import com.intellij.psi.PsiElementVisitor
+import com.intellij.psi.PsiWhiteSpace
+import com.intellij.psi.impl.source.tree.LeafPsiElement
+import com.intellij.psi.util.PsiTreeUtil
+import org.jetbrains.dokka.base.transformers.pages.samples.SamplesTransformer
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.kotlin.psi.*
+import org.jetbrains.kotlin.psi.psiUtil.allChildren
+import org.jetbrains.kotlin.psi.psiUtil.prevLeaf
+import org.jetbrains.kotlin.psi.psiUtil.startOffset
+import org.jetbrains.kotlin.resolve.ImportPath
+import org.jetbrains.kotlin.utils.addToStdlib.safeAs
+import java.io.PrintWriter
+import java.io.StringWriter
+
+class KotlinWebsiteSamplesTransformer(context: DokkaContext): SamplesTransformer(context) {
+
+    private class SampleBuilder : KtTreeVisitorVoid() {
+        val builder = StringBuilder()
+        val text: String
+            get() = builder.toString()
+
+        val errors = mutableListOf<ConvertError>()
+
+        data class ConvertError(val e: Exception, val text: String, val loc: String)
+
+        fun KtValueArgument.extractStringArgumentValue() =
+            (getArgumentExpression() as KtStringTemplateExpression)
+                .entries.joinToString("") { it.text }
+
+
+        fun convertAssertPrints(expression: KtCallExpression) {
+            val (argument, commentArgument) = expression.valueArguments
+            builder.apply {
+                append("println(")
+                append(argument.text)
+                append(") // ")
+                append(commentArgument.extractStringArgumentValue())
+            }
+        }
+
+        fun convertAssertTrueFalse(expression: KtCallExpression, expectedResult: Boolean) {
+            val (argument) = expression.valueArguments
+            builder.apply {
+                expression.valueArguments.getOrNull(1)?.let {
+                    append("// ${it.extractStringArgumentValue()}")
+                    val ws = expression.prevLeaf { it is PsiWhiteSpace }
+                    append(ws?.text ?: "\n")
+                }
+                append("println(\"")
+                append(argument.text)
+                append(" is \${")
+                append(argument.text)
+                append("}\") // $expectedResult")
+            }
+        }
+
+        fun convertAssertFails(expression: KtCallExpression) {
+            val valueArguments = expression.valueArguments
+
+            val funcArgument: KtValueArgument
+            val message: KtValueArgument?
+
+            if (valueArguments.size == 1) {
+                message = null
+                funcArgument = valueArguments.first()
+            } else {
+                message = valueArguments.first()
+                funcArgument = valueArguments.last()
+            }
+
+            builder.apply {
+                val argument = funcArgument.extractFunctionalArgumentText()
+                append(argument.lines().joinToString(separator = "\n") { "// $it" })
+                append(" // ")
+                if (message != null) {
+                    append(message.extractStringArgumentValue())
+                }
+                append(" will fail")
+            }
+        }
+
+        private fun KtValueArgument.extractFunctionalArgumentText(): String {
+            return if (getArgumentExpression() is KtLambdaExpression)
+                PsiTreeUtil.findChildOfType(this, KtBlockExpression::class.java)?.text ?: ""
+            else
+                text
+        }
+
+        fun convertAssertFailsWith(expression: KtCallExpression) {
+            val (funcArgument) = expression.valueArguments
+            val (exceptionType) = expression.typeArguments
+            builder.apply {
+                val argument = funcArgument.extractFunctionalArgumentText()
+                append(argument.lines().joinToString(separator = "\n") { "// $it" })
+                append(" // will fail with ")
+                append(exceptionType.text)
+            }
+        }
+
+        override fun visitCallExpression(expression: KtCallExpression) {
+            when (expression.calleeExpression?.text) {
+                "assertPrints" -> convertAssertPrints(expression)
+                "assertTrue" -> convertAssertTrueFalse(expression, expectedResult = true)
+                "assertFalse" -> convertAssertTrueFalse(expression, expectedResult = false)
+                "assertFails" -> convertAssertFails(expression)
+                "assertFailsWith" -> convertAssertFailsWith(expression)
+                else -> super.visitCallExpression(expression)
+            }
+        }
+
+        private fun reportProblemConvertingElement(element: PsiElement, e: Exception) {
+            val text = element.text
+            val document = PsiDocumentManager.getInstance(element.project).getDocument(element.containingFile)
+
+            val lineInfo = if (document != null) {
+                val lineNumber = document.getLineNumber(element.startOffset)
+                "$lineNumber, ${element.startOffset - document.getLineStartOffset(lineNumber)}"
+            } else {
+                "offset: ${element.startOffset}"
+            }
+            errors += ConvertError(e, text, lineInfo)
+        }
+
+        override fun visitElement(element: PsiElement) {
+            if (element is LeafPsiElement)
+                builder.append(element.text)
+
+            element.acceptChildren(object : PsiElementVisitor() {
+                override fun visitElement(element: PsiElement) {
+                    try {
+                        element.accept(this@SampleBuilder)
+                    } catch (e: Exception) {
+                        try {
+                            reportProblemConvertingElement(element, e)
+                        } finally {
+                            builder.append(element.text) //recover
+                        }
+                    }
+                }
+            })
+        }
+
+    }
+
+    private fun PsiElement.buildSampleText(): String {
+        val sampleBuilder = SampleBuilder()
+        this.accept(sampleBuilder)
+
+        sampleBuilder.errors.forEach {
+            val sw = StringWriter()
+            val pw = PrintWriter(sw)
+            it.e.printStackTrace(pw)
+
+            this@KotlinWebsiteSamplesTransformer.context.logger.error("${containingFile.name}: (${it.loc}): Exception thrown while converting \n```\n${it.text}\n```\n$sw")
+        }
+        return sampleBuilder.text
+    }
+
+    val importsToIgnore = arrayOf("samples.*", "samples.Sample").map { ImportPath.fromString(it) }
+
+    override fun processImports(psiElement: PsiElement): String {
+        val psiFile = psiElement.containingFile
+        return when(val text = psiFile.safeAs<KtFile>()?.importList) {
+            is KtImportList -> text.let {
+                it.allChildren.filter {
+                    it !is KtImportDirective || it.importPath !in importsToIgnore
+                }.joinToString(separator = "\n") { it.text }
+            }
+            else -> ""
+        }
+    }
+
+    override fun processBody(psiElement: PsiElement): String {
+        val text = processSampleBody(psiElement).trim { it == '\n' || it == '\r' }.trimEnd()
+        val lines = text.split("\n")
+        val indent = lines.filter(String::isNotBlank).map { it.takeWhile(Char::isWhitespace).count() }.minOrNull() ?: 0
+        return lines.joinToString("\n") { it.drop(indent) }
+    }
+
+    private fun processSampleBody(psiElement: PsiElement) = when (psiElement) {
+        is KtDeclarationWithBody -> {
+            val bodyExpression = psiElement.bodyExpression
+            val bodyExpressionText = bodyExpression!!.buildSampleText()
+            when (bodyExpression) {
+                is KtBlockExpression -> bodyExpressionText.removeSurrounding("{", "}")
+                else -> bodyExpressionText
+            }
+        }
+        else -> psiElement.buildSampleText()
+    }
+}
\ No newline at end of file
diff --git a/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/SamplesTransformerPlugin.kt b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/SamplesTransformerPlugin.kt
new file mode 100644
index 00000000..e39a3cda
--- /dev/null
+++ b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/kotlin/org/jetbrains/dokka/kotlinlang/SamplesTransformerPlugin.kt
@@ -0,0 +1,15 @@
+package org.jetbrains.dokka.kotlinlang
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+class SamplesTransformerPlugin : DokkaPlugin() {
+    private val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    val kotlinWebsiteSamplesTransformer by extending {
+        CoreExtensions.pageTransformer providing ::KotlinWebsiteSamplesTransformer override dokkaBase.defaultSamplesTransformer order {
+            before(dokkaBase.pageMerger)
+        }
+    }
+}
\ No newline at end of file
diff --git a/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
new file mode 100644
index 00000000..2ac2cd5f
--- /dev/null
+++ b/integration-tests/gradle/projects/stdlib/dokka-samples-transformer-plugin/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1 @@
+org.jetbrains.dokka.kotlinlang.SamplesTransformerPlugin
\ No newline at end of file
diff --git a/integration-tests/gradle/projects/stdlib/stdlib.diff b/integration-tests/gradle/projects/stdlib/stdlib.diff
index c009e788..71d27c99 100644
--- a/integration-tests/gradle/projects/stdlib/stdlib.diff
+++ b/integration-tests/gradle/projects/stdlib/stdlib.diff
@@ -37,7 +37,7 @@ diff --git a/build.gradle b/build.gradle
 index aa8f21b..dd6a2ae 100644
 --- a/build.gradle
 +++ b/build.gradle
-@@ -1,80 +1,424 @@
+@@ -1,80 +1,428 @@
 +import org.jetbrains.dokka.Platform
 +
  plugins {
@@ -74,10 +74,11 @@ index aa8f21b..dd6a2ae 100644
 +    jcenter()
  }
  
--dependencies {
+ dependencies {
 -  dokka "org.jetbrains.dokka:dokka-fatjar:$dokka_version"
--}
--
++  dokkaPlugin project(":dokka-samples-transformer-plugin")
+ }
+
 -final File dokkaHome = new File(buildDir, "dokka-home")
 -task setupDokka(type: Sync) {
 -  from configurations.dokka
@@ -542,7 +543,7 @@ diff --git a/settings.gradle b/settings.gradle
 index 5209245..bd38b18 100644
 --- a/settings.gradle
 +++ b/settings.gradle
-@@ -1,5 +1,18 @@
+@@ -1,5 +1,19 @@
 +pluginManagement {
 +    resolutionStrategy {
 +        eachPlugin {
@@ -562,3 +563,4 @@ index 5209245..bd38b18 100644
  include 'kotlin_native'
  include 'kotlin_big'
 -include 'ant'
++include 'dokka-samples-transformer-plugin'
\ No newline at end of file
diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
index 4f56ba55..a5b61b1d 100644
--- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
+++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/StdlibGradleIntegrationTest.kt
@@ -3,7 +3,8 @@ package org.jetbrains.dokka.it.gradle.kotlin
 import org.gradle.testkit.runner.TaskOutcome
 import org.jetbrains.dokka.it.S3Project
 import org.jetbrains.dokka.it.copyAndApplyGitDiff
-import org.jetbrains.dokka.it.gradle.*
+import org.jetbrains.dokka.it.gradle.AbstractGradleIntegrationTest
+import org.jetbrains.dokka.it.gradle.BuildVersions
 import org.junit.runners.Parameterized
 import java.io.File
 import kotlin.test.*
@@ -28,6 +29,16 @@ class StdlibGradleIntegrationTest(override val versions: BuildVersions) : Abstra
         templateProjectDir.listFiles().orEmpty()
             .forEach { topLevelFile -> topLevelFile.copyRecursively(File(projectDir, topLevelFile.name)) }
 
+        val pluginDir = File("projects", "stdlib/dokka-samples-transformer-plugin")
+        pluginDir.listFiles().orEmpty()
+            .forEach { topLevelFile ->
+                topLevelFile.copyRecursively(
+                    File(
+                        projectDir.resolve("dokka-samples-transformer-plugin").also { it.mkdir() }, topLevelFile.name
+                    )
+                )
+            }
+
         copyAndApplyGitDiff(File("projects", "stdlib/stdlib.diff"))
     }